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64 Display Window and Trace 


The C structures, variables, and routines detailed in this section control the type and location 
of certain displays on the INTERVIEW. These displays can be grouped into three categories. 


The first display area is the prompt line, the second line on all Run-mode screens. 


The second type of display utilizes the Display Window, available as a selection on the Display 
Setup portion of the Line Setup menu, or conditionally accessible via softkey during Run 
mode, To write to the Display Window, use the pos_cursor (or restore_cursor) and displayc, 
displayf, or displays routines. When using Display Window, you may position the cursor 
before output is generated on the screen. 


The third type of display utilizes one or a combination of the eight available trace buffers. 
Trace screens are conditionally accessible-via softkey during Run mode. Seven user-traces 
appear as choices under the User Trace selection on the Display Setup menu. The remaining 
trace is Program Trace, also an option on Display Setup. Program Trace enables you to track 
any or all layers, one or all tests, and movement between states. To write to any of the eight 
trace-screens, use the tracec, tracef, and traces routines. 


NOTE: You may not use the pos cursor routine to position the 
cursor on any trace screen. New lines (or blank lines) may be 
generated via the “\n” specifier. 


Attributes—color, underlining, and font, for example—may be assigned to characters in the 
Display Window and all of the Trace buffers. 


NOTE: Color attributes are applied to the RGB output signal, 
not to the plasma screen. 


64.1 Current Display Mode 


A group of variables keeps track of softkey movement from one display screen to 
another (see Table 64-1). When you move from the Display Window to the Program 
Trace screen, for example, the fasf-event variable display_screen_changed indicates 
the change of display. The coded value for Display Window now is stored in 
prev_display_screen, and the value for Program Trace can be found in 


ernt_display_screen. 
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These variables also distinguish between Run mode and Freeze mode. This 
distinction is important since some keys on the keyboard are mode~dependent. In 
Freeze mode, for instance, cursor keys automatically become operational for scrolling 
through the buffer. The programmer will want to avoid using these keys as 
user~input when crnt_display_screen indicates that the unit is in Freeze mode. 


Table 64-1 
Current Display Variables 


Type Variable Value (hex/decimal) Meaning 


extern fast_event display_screen_changed True when Run-mode 
display-screen Is changed, or 
when Run/Freeze mode Is 
changed. Value [n 
ernt_display_screen l|s etored In 
prev_display_screen, and 
ernt_display-screen |s updated. 
Line Setup configured for 
emulate or monitor mode. 


extern unsigned short crnt_display_screen Contains current display screen 
(low byte) and indicates whether 
unit js In Run mode or Freeze 
mode (high byte). Line Setup 
configured for emulate or 
monitor mode. 


display-screen 


0 no display 

1 single-line data 

2 dual-jine data 

3 single-line data with leads 

4 dual-line data with leads 

41/17 tabular statistics 

12/18 graphic statistics 

21/33 Display Window 

31/49 Program Trace 

41/65 Layer 1 Protocol Trace 

42/66 Layer 2 Protocol Trace 

43/67 Layer 3 Protocol Trace 

44/68 Layer 4 Protocol Trace 

45/69 Layer 5 Protocol Trace 

46/70 Layer 6 Protocol Trace 

47/71 Layer 7 Protocol Trace 

51/81 User Trace 1 

52/82 User Trace 2 

§3/83 User Trace 3 

54/84 User Trace 4 

55/85 User Trace 5 

56/86 User Trace 6 

57/87 User Trace 7 

61/97 TIM package standard stats 

62/98 TIM package aux 
RuniFreeze mode (bit 9) 

100/256 Freeze mode 

0 Run mode 
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Table 64-1 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


extern unsigned short prev_display_screen Contalns previous display screen 


(low byte) and Indicates whether 
unlt was In Run mode or Freeze 
mode {high byte). Line Setup 
configured for emutate or 
monitor mode. 


display-screen 


0 no display 

1 single-line data 

2 dual-line data 

3 single-tine data with leads 

4 dual-line data with leads 

11/17 tabular statistics 

12/18 graphic statistics 

21/33 Olsplay Window 

31/49 Program Trace 

41/65 Layer 1 Protocol Trace 

42/66 Layer 2 Protocol Trace 

43/67 Layer 3 Protocol Trace 

44/68 Layer 4 Protocol Trace 

48/69 Layer 5 Protocol Trace 

46/70 Layer 6 Protocol Trace 

47/71 Layer 7 Protocol Trace 

51/81 User Trace 1 

52/82 User Trace 2 

§3/83 User Trace 3 

54/84 User Trace 4 

§5/85 User Trace 5 

56/86 User Trace 6 

§7/87 User Trace 7 

61/97 © TIM package standard stats 

62/98 TIM package aux 
RuniFreeze mode {bit 9) 

100/256 Freeze mode 

0 Run mode 


64.2 Prompt Line 
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Access to the prompt line is always available via the display_prompt routine, or its 
softkey equivalent, the PROMPT action. Attributes may not be assigned to a prompt 
created via either of these methods. (To create a prompt with attributes, use the 
pos_cursor and displayf routines.) Prompts appear on whatever screen is active at 
the time the prompt is written, including trace screens. With one exception, 
movement to another display erases the prompt. The only screen which retains the 
most recent prompt is the Display Window. 


You may also position the cursor to the prompt line in the Display Window via the 
pos_cursor routine. The initial position of the cursor in the Display Window is at the 
beginning of the prompt tine—row zero, column zero. Anything written to this cursor 
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position in the Display Window will appear as a prompt on any one of the other 
display screens (assuming one of them is active at the time the message is written). 
Position the cursor below the prompt line for messages intended for the Display 
Window only. 


Trace buffers retain no record of prompts. When you write to a trace screen, the 
initial position of the cursor is the line immediately below the prompt line—row one. 
Since you may not position the cursor in trace buffers, all messages written to trace 
buffers are appended at the end of the buffer. You may never access the prompt 
line via ¢racef (or tracec or traces) routines. 


Display Window 


The Display Window preserves one screen, including the prompt line, of user~entered 
messages. When the end of the display screen is reached, the previous messages are 
overwritten, beginning at row one (the line below the prompt line). 


NOTE: Use the keyboard variables and the send_key routine 
explained in Section 72, Other Library Tools, to program the 
Run-mode use of @ and & in the Display Window. (For other 
Run-mode screens, these keys control the playback speed of disk 
data.) 


(A) Variables 


There are variables accessible to the user which provide information about the 
Display Window. Table 64-2 lists the variables and their possible values. Two 
variables indicate the current position of the cursor: current_line stores the row 
number and current_col stores the column number. To find out which attributes 
are active in the Display Window, check the values stored in window_color and 
window_modifier. Color is stored in the high byte of the two-byte variable 
window_color. Enhancements are stored in the low byte. The current font code 
can be found in window_modifier. 


NOTE: Attributes assigned via the %m conversion specifier 
(refer to ¢racef-routine input) to characters in trace buffers will 
not alter the values of window_color and window_modifier. These 
variables refer to the Display Window only. 


The variable display_window_buffer provides the user with access to the 
display-window buffer. This variable is an array of 1,088 Jongs. Each element 
in the array contains one byte of character data and three bytes of attributes. 
The attributes are determined by the current values of window_color and 


window_modifier. 
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Table 64-2 
Display Window Varlables 


Type Variable Value (hex/decimal) Meaning 


extern unsigned short current_line 0-101/0-16 Contains the current row 
number of the cursor position In 
the Display Window. Line Setup 
configured for emulate or 
monitor mode. 


extern unsigned short current_col 0-3f10-63 Contains the current column 
number of the oursor position In 
the Display Window. Line Setup 
configured for emulate or 
Monitor mode. 


extern unsigned short window_color Two-byte varlable. Current 
color selections are Indicated In 
the low byte. Current 
enhancements are Indloated In 
the high byte. Written to by %m 
conversions. Attributes are 
copied Into data words In 
Display Window. Line Setup 
configured for emulate or 
monitor mode. 


lsolate bits of interest via 
bitwise anding (&) of mask with 
variable. Compare result to 
value column. For example, 
underline attribute mask = 
0x100. Therefore window_cclor 
& 0x100 equals O {underline off) 
or 0x100 (underline on). Line 
Setup configured for emulate or 
monitor mode. 


background color mask = 7 (bits 


1-3): 
0 black 
1 blue 
2 green 
3 cyan 
4 red 
5 magenta 
6 yellow 
7 white 
foreground color mask = 0x38 
(bits 4-6): 
0 black 
8 blue 
10/16 green 
18/24 cyan 
20/32 red 
28/40 magenta 
30/48 ysllow 
38/56 white 
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Table 64-2 (continued) 


Type Variable Value (hex/decimal) Meaning 


(window_color continued) 


40/64 


80/128 


0 
100/256 


0 
200/512 


0 
400/1024 


0 
800/2048 


0 
1000/4096 


0 
2000/8192 


0 
4000/16384 


0 
8000/32768 


color blink mask = 0x40 (bit 7): 


no bilnk 
blink 


color strike~thru mask = 0x80 
(bit 8): 


no strike-thru 
strike-thru 


overline mask = 0x100 (bit 9}: 


no overline 
overiine 


blank mask = 0x200 (bit 10): 


no blank 
blank 


underline mask = 0x400 (bit 
tT): 


no underline 
underline 


reverse Image mask = 0x800 (bit 
12}; 


no reverse Image 
reverse image 


hex mask = 0x1000 (bit 13): 


no hex 
hex 


low Intensity mask = 0x2000 (bit 
14): 


no low Intensity 
low Intensity (RS-170 output) 


monochrome blink mask = 
0x4000 (bit 15): 


no monochrome blink 
monochrome blink 


monochrome strike-thru mask = 
Ox8000 (bit 16): 


no monochrome strike-thru 
monochrome strike-thru 
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Table 64-2 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


extern unsigned char 


extern unsigned long 


window_modifler Contalns the current modiflers, 
Line Setup configured for 
emulate or monitor mode. 


font mask = 7 (bits 1-3); 


0 ASCI 

1 special graphic character set 
(refer to Table 64-5) 

2 primary font—code selected on 
Line Setup 

3 alternate font—current 


Implementation Is for call-setup 
phase In X.21 (ASCII) 
7 hexadecimal 


disptay_window_buffer [1088) Array of 32-bit words that make 
up the one-screen Display 
Window. Each word contalns 
three bytes of attributes and a 
one-byte character. Refer to 
Table 64-4, Line Setup 
configured for emulate or 
monitor mode. 


(B) Structures 
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Once the data word is written to the buffer as an element in the 
display_window_buffer array, it can be accessed and written to—and therefore 
changed—the same as any other location in memory. There is an extern array, 
display_window_index_buffer{17], which provides a method of informing the 
display controller on the CPM card that the display needs to be updated. The 
structure of this array is shown in Table 64-3. 


Each element in the display_window_index_buffer array represents a horizontal 
row or fine in the Display Window. Each element is a structure with two 
variables, mpm and cpm. The first variable in the structure, mpm, increments 
automatically whenever a line in the display-window buffer is updated by a 
display routine. (If you write to the buffer directly without using one of the 
display routines, you must increment this variable “manually.”) Its particular 
value at any moment is not important. What is significant is whether or not the 
value of the second variable in the structure, cpm, is the same as mpm. The 
processor on the CPM compares these two variables (for each line) periodically 
to determine if a line in the Display Window needs to be rewritten. If the 
values of the two variables do not match, it means that a line updated in 
memory now needs to be updated by the CPM display-controller software. 
After the display is changed, the value of mpm is copied automatically into cpm. 
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Table 64-3 
Display Window Buffer Structures 


Type Variable Value (hex/decimal) 


Meaning 


Structure Name: display_window_index_buffer [17] 


unsigned char mpm 0-ff/0-255 


unsigned char cpm 0-f1/0-255 


(C) Routines 


An array of structures used for detecting 
changes to the display-window buffer. There are 
seventeen elements In the array, one for each 
line in the Display Window. When a change te 
made to a line In the display-window buffer, the 
corresponding element in the array le accessed. 
If a disptayf routine changes line 3, 
display_window_ index_butfer{3].mpm le 
automatically incremented. The CPM detects 
the difference between 
display_window_index_buffer [3].mpm and 
display_window_index_buffer {3].cpm and 
updates [Ine 3 In the Display Window. Declared 
as type extern struct, 


You must Increment an mpm variable manually 
when you write directly (not vila a display? routine) 
to the Display Window. 


When the MPM updates a line in the 
display-window buffer, this variable Is 
incremented. 


The CPM checks the value of this varlable against 
the value of mpm. If they are different, the 
value in mpm ts copied Into cpm. The updated 
line In MPM Is then presented on the 
display-window screen. 


You may position the cursor before output is generated on the screen via the 
pos_cursor and restore_cursor routines. The pos_cursor routine positions the 
cursor at the row and column you specify. The restore_cursor routine returns 


the cursor to a previous location. 


One routine, displayf, allows you to add attributes to messages in the Display 
Window, including the prompt line. These attributes are listed in Table 64-4. 


Additional routines control the labeling of Display Window softkeys: 
set_dw_fkey_label, show_dw_fkey_labels, highlight_dw_fkey_label, and 


unhighlight_dw_fkey_label. 
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displayc 
Synopsis 


extern void displaye(character); 
const char character; 


Description 
The displayc routine outputs a single ASCII character to the Display Window 


screen. The placement of the output on the screen may be controlled via the 
pos_cursor routine. Attributes may not be used in displayc. 


Inputs 


The parameter value may be given as a hexadecimal, octal, or decimal constant; 
as an alphanumeric constant inside of single quotes; or as a variable. A 
hexadecimal value must be preceded by the prefix Ox or 0X; an octal value must 
be preceded by the prefix 0. If no prefix appears before the input, the number 
is assumed to be decimal. Valid numeric entries are 00 to 127, decimal. An 
alphanumeric character placed between single quotes will be output as is to the 
display. 


Example 


The displayc entries on the left output the character given on the right, at the 
cursor location on the Display Window screen: 


displayc{‘a’); 
displaye(65); 
displaye(Ox65); 
displayc(065); 


wo > BP 


displayf 
Synopsis 


extern int displayf(format_ptr, ... ); 
const char * format_ptr; 


Description 

The displayf routine writes output to the Display Window screen, under control 
of the string pointed to by format_ptr that specifies how subsequent arguments 
are converted for output. If there are insufficient arguments for the format, the 
behavior is undefined. If the format is exhausted while arguments remain, the 
excess arguments are evaluated but otherwise ignored. The displayf routine 
returns when the end of the format string is encountered. The placement of the 
output on the screen may be controlled via the pos_cursor routine. 
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Inputs 


The format is composed of zero or more directives: ordinary characters (not 
%), which are copied unchanged to the output stream; and conversion 
specifications, each of which results in fetching zero or more subsequent 
arguments. Each conversion specification is introduced by the character %. 
After the %, the following appear in sequence: 


Zero or more flags that modify the meaning of the conversion specification. 
The flag characters and their meanings are: 


- The result of the conversion will be left-justified within the field. 
+ The result of a signed conversion will always begin with a plus or 
minus sign. 


space If the first character of a signed conversion is not a sign, a space will 
be prepended to the result. If the space and + flags both appear, the 
Space flag will be ignored. 


# The result is to be converted to an “alternate form.” For d and i 


conversions, the flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a zero. For x (or 
X) conversion, a nonzero result will have Ox (or OX) prepended to it. 
For u conversions, the argument is displayed in small hex characters. 
For example, displayf (“%#u”, 258); yields "%. For c and s 
conversions, if the argument contains a newline character, it is 
displayed as 'r. 


An optional decimal integer specifying a minimum field width. If the 
converted value has fewer characters than the field width, it will be padded 
on the left (or right, if the left adjustment flag, described above, has been 
given) to the field width. The padding is with spaces unless the field width 
integer starts with a zero, in which case the padding is with zeros. 


An optional precision that gives the minimum number of digits to appear for 
the d, i, o, u, x, and X conversions, the maximum number of characters to 
be written from an array in an s conversion, or the number of characters to 
be written from an array in an H conversion (overriding the usual 
null-termination of strings). The precision takes the form of a period (.) 
followed by an optional decimal integer; if the integer is omitted, it is treated 
as zero. The amount of padding specified by the precision overrides that 
specified by the field width. 
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An optional h specifying that a following d, i, o, u, x, or X conversion 
specifier applies to a short int or unsigned short int argument (the argument 
will have been promoted according to the integral promotions, and its value 
shall be converted to short int or unsigned short int before printing); or an 
optional | specifying that a following d, i, o, u, x, or X conversion specifier 
applies to a long int or unsigned long int argument. If an h or | appears 
with any other conversion specifier, it is ignored. 


A character that specifies the type of conversion to be applied. (Special AR 
extensions have been added.) The conversion specifiers and their meanings 
are: 


d, i, o, uy x, X- 


The int argument is converted to signed decimal (d or i), unsigned 
octal (0), unsigned decimal (u), or unsigned hexadecimal notation (x 
or X); the letters abcdef are used for x conversion and the letters 
ABCDEF for X conversion. The precision specifies the minimum 
number of digits to appear; if the value being converted can be 
represented in fewer digits, it will be expanded with leading zeros. 
The defauit precision is 1. The result of converting a zero value with 
a precision of zero is no characters. 


c The inf argument is converted to an unsigned char, and the resulting 
character is written. 
s The argument shall be a pointer to a null-terminated array of 8-bit 


chars. Characters from the string are written up to (but not including) 
the terminating null character: if the precision is specified, no more 
than that many characters are written. The string may be an array 
into which output was written via the sprintf routine. (If the string 
pointed to is an array which has been written via the stracef routine, 
you must use %b rather than %s to display it.) 

p The argument shall be a pointer to void. The value of the pointer is 
converted to a sequence of printable characters, in this format: 
0000:0000. There are always exactly 4 digits to the right of the 
colon. The number of digits to the left of the colon is determined by 
the pointer’s value and the precision specified. Use this conversion to 
display 80286 memory addresses. The 16-bit segment number will 
appear to the left of the colon and the 16-bit offset to the right. 


% A % is written. No argument is converted. 

\n Displays . No argument is converted. When \n is not preceded by 
a %, it is not a conversion specifier. Instead of a ‘r being displayed, a 
newline (+) will be executed. 

H displays a character array (pointed to by the argument) as small hex 
characters. If precision is specified, it is used as the length of the 
array (overriding the usual null-termination of strings). 
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The argument shall be a pointer to an array of 32-bit words. 
Characters from the string are written up to (but not including) the 
terminating word containing a null character: if the precision is 
specified, no more than that many words are written. If the string 
pointed to is an array into which output was written via the stracef 
routine, you must use %b rather than %s to display it. (To display 
the information in an array written to via sprintf, use %s.) 


The argument is a /ong integer that indicates attributes to be assigned 
to subsequent characters. Attributes stay “on” until they are 
specifically turned. “off” with. another %m conversion specifier. The 
lowest-order byte contains primarily font code. The next higher byte 
is not used to set attributes. (In the display-window buffer, this 
second byte is reserved for character coding.) The third byte hoids 
color information. The high byte indicates which enhancements 
should be invoked. 


Attributes are written automatically to window_color and 
window_modifier variables, then copied into subsequent 32-bit data 
words in the Display Window. Table 64-4 shows the format of this 
32-bit word. 


Attributes may not be assigned as a one-byte value. Even if you want 
to alter only one attribute setting, color for example, you must include 
it as part of a jong. Append an “L” at the end of the hexadecimal 
code specifying attributes to indicate the value is a Jong. 


NOTE: If you are specifying an attribute in a lower-order byte of the 
long, color for example, and you want the high byte (or bytes) to be 
zero, you may omit the high byte provided you have the “L” 
appended at the end of the hexadecimal code. The high byte (or 
bytes) will be left-padded with zeroes. For example, 0x200000L is 
converted to 0x00200000L. Associated characters will be displayed 
on a color monitor as green on a black background, as dictated by the 
hexadecimal 20 in the third byte. Enhancements are controlled in the 
high byte, now assigned a value of zero. Any enhancements 
previously turned “on” will be turned “off.” 


If a conversion specification is invalid, the behavior is undefined. 


If any argument is or points to an aggregate (except for an array of characters 
using %s conversion or any pointer using %p conversion), the behavior is 
undefined. 


In no case does a nonexistent or small field width cause truncation of a field; if 
the result of a conversion is wider than the field width, the field is expanded to 
contain the conversion result. 
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Returns 
The displayf routine returns the number of characters displayed. 
Example 


To display a date and time in the form “Sunday, July 3, 10:02,” where weekday 
and month are pointers to strings: 


LAYER: 1 

{ 

unsigned char ‘weekday {10]; 
unsigned char month [10}; 
unsigned short day; 
unsigned char hour; 
unsigned char min; 


) 
STATE: output_to_display_window 
CONDITIONS: KEYBOARD * " 
ACTIONS: 
{ . 
displayf( “%s, %s %d, %.2d:%.2d\n", weekday, month, day, hour, min); 
sprintf 


The sprintf routine is similar to the displayf routine. displayf writes output with 
or without attributes directly to the Display Window. sprintf, fully documented 
in Section 67.3, writes output to a character array in which attributes are not 
supported. This routine is useful for writing formatted output to a display, 
printer, or file. 


See also stracef in Section 64.4(C). 
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Table 64-4 
Display Window/Trace Buffer 32-Blt Data Word 


Bit Mask (hex)t Input (hex) tT Meaning 


Modifier attributes, font for example, 
are contained In the low byte of the 
32-bit word. 


1-3 00000007L Font: 


O0000000L ASCII . 

O0000001L speolal graphic character set (refer to 
Table 64-5) 

00000002L primary font—oode selected on Line 
Setup 

00000003L alternate font—current Implementation 
is for call-setup phase in X.21 (ASCII) 

00000007L hexadecimal 


> 


00000008L : 
(used in trace buffer only; should not 
be altered by user) 


O0OC00COL only value In modifier in trace buffer 
header 

00000008L Character |s not displayable but 
contalns control Info used Internally by 
the trace logio. When a “\n" is 
Iinciuded In a tracef routine, for 
example, a new line ls generated, but 
nothing Js displayed on the trace 
screen. The tracef routine 
automatically sete this bit before the 
32-bit word Is written Into 
trace_buf.array. 


§-8 OOO000fOL 00000000L unused, but should be zero 
9-16 OOOOffOOL 00000000L © Character data ie contalned In the 


second byte of the jong word. Input 
should be 00 In all %m conversions. 


f{ Use the masks to change attributes of characters In the Display Window or trace buffer. In the Display Window, 
characters are represented In the second byte of the /ongs that comprise the 1,088 array elements In 
aisplay_window_buffer. in the irace_buf structure, the characters are represented In the second byte of the 
longs that make up the trace_buf.array. To change one attribute of a character while leaving the others 
unchanged: 


display_window_buffer[position] = {(display_window_buffer{position] & (~attribute-mask)) | input); 


To change only the font of the twenty-first character in the trace buffer from Its current setting to the special 
graphic font, for example: 


i2_trbuf,array{20] = ((trace_buf.array{20] & (~-Ox00000007L)) | Ox00000001L); 
Analing the character with the mask wii Indicate the current setting of an attribute: 


if (12_trbuf.array{20] & 0x00000007L) equals 2, then the 21st character In the Trace 2 user-trace buffer is 
belng displayed In the font selected on the Line Setup menu. 


++ in displayf routines, the %m conversion specifier writes Input to the window_color and window_modifler 
varlables. These variables are copied into subsequent data words In the Display Window. In tracef routines, the 
%m conversion specifier writes Input to trace_buffer_header. The header Is then copled Into each subsequent 
data word In the buffer. Combine attributes vila hexadecimal addition. 
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Table 64-4 (continued) 


Bit Mask (hex) tmput (hex) Meanling 
Color |s contained in the third byte of 
the jong. Combine color attributes via 
hexadecimal addition. 
17-19 00070000L Background color: 
00O000000L black 
00010000L blue 
00020000L green 
00030000L cyan 
00040000L red 
00Q50000L magenta 
O0O006C000L yellow 
00070000L white 
20-22 00380000L Foreground color: 
00000000L black 
00080000L blue 
00j00000L green 
00180000L cyan 
00200000L red 
00280000L magenta 
00300000L yellow 
00380000. white. 
23 00400000L Color blink: 
00Q00000L no blink 
00400000L blink 
24 o0Booc00L Cotor strike-thru: 
00090000L no strike-thru 
00800000L strike-thru 
Enhance attributes, underlining for 
example, are contained in the high 
byte of the jong. Combine 
enhancements via hexadecimal 
: addition. 
25 Q1000000L : 
{for monochrome and color) 
Q0000000L no overiine 
010000001. overline 
26 Q2000000L Blank: 
QQ000000L monochrome display, color display 
Q2000000L monochrome no display, color display 
27 04000000L Underline: 
(for monochrome and color} 
QQ000000L no underline 
04000000L underline 
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Table 64-4 (continued) 


Bit Mask (hex) Input (hex) Meaning 

28 08000000L Monochrome reverse Image: 
00000000L no reverse Image 
QB0C0000L reverse Image 

29 10000000L Hex: 
O0000000L no hex 
1Q000000L hex 

30 20000000L Monochrome tow Intensity: 
Q0000000L no low Intensity 
2Q000000L low intensity (RS-170 interface) 

31 40000000L Monochrome blink: 
Q0000000L no blink 
40000000L blink 

32 §0000000L Monochrome strike~thru: 
QQ000000L no strike-thru 
80000000L strike-thru 
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Table 64-5 
Special Graphic Character Set} 


Display Input (hex/decimal) Display Input (hex/decimal) 
5 0 _ 10/28 
I 1 | 14/29 
aa 2 T 10/30 
a 3 + 11/31 
» 4 4 20/32 
« 5 t 21/33 
a. 6 N 22/34 
3] 7 ts 23/35 
& 8 | 24/36 
fa] 9 N 25/37 
A a/10 y 26/38 
a b/11 | 27/39 
oO c/12 N 28/40 
d,11/13,17 a 29/41 
Pn) e/14 I 2a/42 
a #115 W. 2b/43 

10/16 . w 20/44 

‘A: 12/18 = 24/45 
£ 13/19 * 20/46 
~ 14/20 bad 2t/47 
a 15/21 = 30/48 
16/22 (space) 31/49 
4 17/23 4 32/50 
‘ 18/24 + 33/51 
r 19/25 € 34/52 
1 1a/26 > 35/53 
+ 1b/27 = 36/54 


Ua 


+ Written to the Display Window or a trace buffer when low (modifier) byte of 32-bit data word = 0x01. 
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Table 64-5 (continued) 


Display Input (hex/decimal) Display Input (hex/decimal) 
¥ 80/128 a) 9a/154 
* 81/129 y 9b/155 
, 82/130 S 90/156 
4 83/131 R 90/157 
. 84/132 R 90/158 

85/133 y 9f/169 

2 86/134 5S a0/160 
r 87/135 F at/161 

4 88/136 y a2/162 
oo] 89/137 F a3/163 
I 8a/138 h a4/164 
a 8b/139 t aS/165 
+ 80/140 = a6/166 
a 8d/141 2 a7/167 
3 8e/142 x a8/168 
) 8f/143 3 a9/169 
a 90/144 rh) aa/170 
P 91/145 E ab/171 
4 92/146 2 ac/172 
” 93/147 \ ad/173 
I 94/148 rt ae/174 
4 95/149 ? af/175 
y)) 96/150 ES b0/176 
+ 97/151 4 b1/177 
4 98/152 # b2/178 
+ 99/153 = b3/179 
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Table 64-5 (continued) 


Display Input (hex/decimal) Display Input (hex/decimal) 
- b4/180 A ce/206 
2 b5/181 A of/207 
E| b6/182 E 0/208 
3 b7/183 2 di/209 
b8/184 ff d2/210 
Ib b9/185 om 3/211 
bL ba/186 6 04/212 
o bb/187 0 45/213 
) bo/188 a 46/214 
) bd/189 to d7/215 
. be/190 yg d8/216 
. bf/191 Oo 49/217 
¢ c0/192 s) da/218 
u 1/193 Cc. db/219 
é 02/194 £ dce/220 
4 03/195 B dd/221 
4 04/196 R de/222 
a c5/197 f df/223 
4 06/198 a 00/224 
¢ ¢7/199 i e1/225 
é 8/200 fa) 02/226 
é 09/201 u 03/227 
e ca/202 A 04/228 
t cb/203 Ni 05/229 
i cc/204 = 26/230 
i ed/205 2} 97/231 
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Table 64-5 (continued) 


64-20 


Display Input (hex/decimal) Display Input (hex/decimal) 
é 28/232 i ed/237 
r 09/233 - 60/238 
= ea/234 § ef/239 
: eb/235 i {0/240 
YG 60/236 
displays 
Synopsis 


extern void displays(string ptr); 

const char * string ptr; 

Description 

The displays routine writes output to the Display Window screen, under control 
of the string that is pointed to by string_ptr. The displays routine returns when 
the end of the string is encountered. The placement of the output on the screen 
may be controlled via the pos_cursor routine. Attributes may not be used in 
displays. 

Inputs 

The input is a pointer to a string composed of zero or more ordinary characters. 
Octal or hexadecimal values also may be included in the string, with octal 


preceded by \ and hex by \x. Pad each value to three integers with leading 
zeroes. 


Example 
The following entry 


pos_cursor( 0, 0 ); 
displays(“End of test.”); 


produces the following output on the prompt line: 
End of test. 


The following coding produces the same output: 


pos_cursor( 0, 0 ); 

const char * string_ptr; 

String ptr = “End of test.”; | 
displays (string_ptr); 
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display_prompt 
Synopsis 


extern vold display prompt (string pir); 
const char * string ptr; 


Description 


The display_prompt routine displays a designated string at the beginning of the 
prompt line. The cursor is automatically positioned at row zero, column zero. 
Once the prompt.is. written,.the.cursor is returned to its previous position. The 
softkey equivalent of this routine is the PROMPT action. The prompt is visible on 
whichever display screen is active at the time the prompt is written. The most 
recent prompt is retained in the Display Window. Attributes may not be used in 
display_prompt. 


Inputs 


The input is a pointer to a string composed of zero or more ordinary characters. 
Octal or hexadecimal values also may be included in the string, with octal 
preceded by \ and hex by \x. Pad each value to three integers with leading 
zeroes. 


Example 


Refer to the example provided for the displays routine. The same string could . 
be output to the same position without calling the pos_cursor routine: 


display_prompt(“End of test."”); 
or 
const char * string_ptr; 


string ptr = “End of test.”; 
display_promp!t (string ptr); 


pos_cursor 
Synopsis 


extern unsigned int pos_cursor(row, column); 

unsigned char row; 

unsigned char column; 

Description 

This routine positions the cursor on the Display Window screen by row and 
column numbers. 


NOTE: The pos_cursor routine may not be used to position the 
cursor on trace screens. 
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Inputs 
The first parameter is the row number. Possible values: 0-16. (The top line of 
the screen is reserved for header information and cannot be written to.) 


The second parameter is the column number. Possible values: 0-63. 


Returns 

The pos_cursor routine returns the previous cursor position in the form of an 
unsigned int. The high byte contains the row number, the low byte identifies the 
column number.. 


Example 
To position the cursor at the far left edge of the prompt line on the Display 
Window, enter zero for both parameters. 


LAYER: 4 
STATE: write_to_display 
CONDITIONS: KEYBOARD ° ” 
ACTIONS: 
{ 


pes_cursor(0,0); 
displays{"Display on prompt line.”); 
} 


restore_cursor 
Synopsis 


extern void restore_cursor(position); 
unsigned int position; 


ription 


The restore_cursor routine returns the cursor to a previous position, 


NOTE: The restore_cursor routine may not be used to position 
the cursor on trace screens. 


Inputs 


The only input is an unsigned int in the same form that is used by the returned 
value of the pos_cursor routine. The high byte identifies the row number, The 
low byte identifies the column number. 


Example 


Suppose the cursor is located in the middle of the Display Window. You want 
to write a message to the prompt-line, but return to your previous location on 
the screen to continue your display. 
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{ 


unsigned int previous; 


STATE: display 
CONDITIONS: KEYBOARD * " 
ACTIONS: 
{ 
pos_cursor(8,0); 
displays(“This tine begins on row 8, column O of the Display Window.”); 
previous = pos_cursor(0,0); 
displays(“This sentence is on the prompt line.”); 
restore_cursor(previous); 
displays(“This sentence begins on row 8, column 58 of the Display Window, the 
position of the cursor at the time pos_cursor(0,0) was called.”); 


set_dw_fkey_label 
Synopsis 


extern void set_dw_fkey_label(fkey, tabel_ptr); 
unsigned int fkey; 
const char * label_ptr; 


Description 


The set_dw_fkey_label routine assigns a user-defined label to a specified Display 
Window soltkey. A call to set_dw_fkey_labe! does not automatically update the 
label on the Display Window screen. You must press the Run-mode DSP WND 
softkey at least once to access the new rack of softkey labels. After that, you 
may update the display by calling the show_dw_fkey_labels routine. 


You may monitor the softkeys associated with your labels only when the 
user-defined rack of softkeys is active, i.e., the labels are displayed. When the 
labels are displayed and a function key pressed, the fast-event variable 
keyboard_new_any_key comes true and the variable keyboard_any_key is updated 
according to the values listed below. See Section 72.2 for more information on 
these variables. 


i 


Hex Value 


197 
198 
199 
19a 
19b 
19c 
19d 
19e 


BEEEEE88 


There is no Protocol Spreadsheet softkey equivalent of this routine. 
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Inputs 


The first parameter identifies the number of the function key to be labeled. 
Integers from 1 through 8 are valid values. If the specified value is out of the 
valid range, the label is not assigned to any softkey. 


The second parameter is a pointer to a null-terminated string, i.e., the label that 
should appear below the designated softkey. The label string has a maximum 
length of seven characters. If it has fewer than seven characters, it is padded to 
the right with spaces. If it has more than seven characters, only the first seven 
are used. 


Example 


In the example below a label is assigned to each of the softkeys in the Display 
Window. To see the labels displayed, press DSP WND. 


LAYER: 1 
STATE: define_labels 

CONDITIONS: ENTER_STATE 
ACTIONS: 
{ 
set_dw_fkey_label(I, “ one"); 
set_dw_fkey label(2, “ two"); 
set_dw_fkey_label(3, “ three”); 
set_dw_fkey_iabel(4, “ four"); 
set_dw_fkey_labei(5, “ five"); 
set_dw_fkey_label(6, “ six”); 
set_dw_fkey_iabel(7, “ seven”); 


show_dw_fkey_labels 
Synopsis 


extern vold show_dw_fkey_labels(); 


Description 

The show_dw_fkey_labels routine updates the display of all user-assigned softkey 
labels in the Display Window. For this routine to have any effect, the DSP WND 
softkey must have been pressed at least once and the user-assigned labels must 
be currently displayed. There is no Protocol Spreadsheet softkey equivalent of 
this routine. 


Example 

Enter the Display Window by pressing DSP WND in Run mode. Then alternate 
between two defined softkey rack by pressing (labeled MORE) from either 
rack. 

{ 

extern fast_event keyboard_new_any_Kkey; 


extern volatile unsigned short keyboard_any_key; 


} 
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LAYER: 1 
STATE: first_rack 
CONDITIONS: ENTER_STATE 
ACTIONS: 
{ 
Set_dw_fkey_fabei(1, “ one”); 
set_dw_fkey_labet(2, “ two”); 
set_dw_fkey_label(3, “ three”); 
set_dw_fkey_label(4, “ four”); 
set_dw_fkey_labet(5, “ five”); 
set_dw_fkey_label(6, “ six’); 
Set_dw_fkey_labet(7, “ seven”); 
Set_dw_fkey_label(8, “ MORE”); 
show_dw_fkey_labels(); 
} 
NEXT_STATE: second_rack 
STATE: second_rack 

CONDITIONS: 
{ . 
keyboard_new_any key && (keyboard_any_key == 0x19e) /* MORE pressed on rack 1 */ 
} 


ACTIONS: 

{ 

Set_dw_fkey label(i, “ eight”); 

set_dw_fkey_labei(2, “ nine”); 

set_dw_fkey_tabel(3, “ ten"); 

set_dw_fkey label(4, “ eleven”); 

set_dw_fkey_labet(5, “ twelve”); 

Set_dw_fkey label(6, “ thirtn”); 

set_dw_fkey_label(7, “ fourtn”); 

set_dw_fkey_tabel(8, “ MORE”); 

show_dw_fkey labets(); 

} 

NEXT_STATE: walt_for_more 
STATE: walt_for_more 

CONDITIONS: 

{ 

keyboard_new_any_key && (keyboard_any_key == Ox/9e) /* MORE pressed on rack 2 */ 


) 
NEXT_STATE: first_rack 


highlight_dw_fkey_label 
Synopsis 


extern void highlight_dw_fkey_label (fkey) ; 
unsigned int fkey; 


Description 
The highlight_dw_fkey_label displays a specified user-defined softkey label in 


reverse video. This routine applies to the Display Window only. There is no 
Protocol Spreadsheet softkey equivalent of this routine. 
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Inputs 


The only parameter identifies the number of the function key whose label is to 
be highlighted. Integers from 1 through 8 are valid values. Values outside this 
range are ignored. 


Example 


This example is similar to the one for show_dw_fkey_labels except that each 
time a softkey is pressed, its label is highlighted and any previous highlighted 
label is returned to normal video, 


{ 
extern fast_event keyboard_new_any_key; 
extern volatile unsigned short keyboard_any_key; 
unsigned short current_fkey; /* currently highlighted fkey label */ 
} 
LAYER: 1 
STATE: first_rack 
CONDITIONS: ENTER_STATE 
ACTIONS: 
{ 
unhighlight_dw_fkey_labei(current_fkey); ra 
set_dw_fkey_label(i, “ one”); . 
set_dw_fkey_labei(2, “ two”); 
set_dw_fkey_ltabei(3, “ three”); 
set_dw_fkey_label(4, “ four”); 
set_dw_fkey_labei(S, “ five”); 
set_dw_fkey_label(6, “ six"); 
set_dw_fkey_label(7, “ seven”); 
Set_dw_fkey_labei(8, “ MORE"); 
current _fkey = 0; /° 0 not in range — no fkey highlighted */ 
Show_dw_fkey_labeis{); 


) 
NEXT_STATE: second_rack 
STATE: second_rack 
CONDITIONS: 
{ 
keyboard_new_any_key && (keyboard_any_key == Ox19e) /* MORE pressed on rack 1 */ 
} 
ACTIONS: 
{ 
unhighlight_dw_fkey_label (current_fkey); 
current_fkey = 0; /* no highlight on initial display of rack 2 “/ 
set_dw_fkey_label(!, " eight”); 
set_dw_fkey_label(2, “ nine”); 
set_dw_fkey_label(3, “ ten”); 
set_dw_fkey_label(4, “ eleven”); 
set_dw_fkey_label(5, “ twelve”); 
set_dw_fkey_label(6, “ thirtn”); 
set_dw_fkey_label(7, “ fourtn”); 
set_dw_fkey_label(8, “ MORE”); 
show_dw_fkey_labets(); 
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NEXT_STATE: walt_for_more 
CONDITIONS: 


{ 
. /* key other than MORE pressed on rack 1 */ 

keyboard_new_any_key && ((keyboard_any_ i >= Ox197) && (keyboard, any_key <= 
Ox!9d)) 


} 
ACTIONS: 


unhighlight_dw_fkey_tabel(current_fkey); 
current_fkey = keyboard_any_key - 0x196; 
highlight_dw_fkey_label(current_fkey); 


STATE: walt_for_more 
CONDITIONS: 


{ 
/* key other than MORE pressed on rack 2 */ 

keyboard_new_any_key && ((keyboard_any_key >= Ox197) && (keyboard_any_key <= 
Ox19d)) 


} 
ACTIONS: 


{ 

unhighlight_dw_fkey_label(current_fkey); 
current_fkey = keyboard_any_key - 0x196; 
highlight_dw_fkey_ltabel(current_fkey); 


} 
CONDITIONS: 


{ 
keyboard_new_any_key && (keyboard_any_key == Ox!9e) /* MORE pressed on rack 2 °/ 


) 
NEXT_STATE: first_rack 


unhighlight_dw_fkey_label 
Synopsis 


extern void highlight_dw_fkey_label{fkey); 

unsigned int fey; 

Description 

The unhighlight_dw_fkey_label displays a specified user-defined softkey label in 


normal video. This routine applies to the Display Window only. There is no 
Protocol Spreadsheet softkey equivalent of this routine. 


Inputs 


The only parameter identifies the number of the function key to be 
unhighlighted. Integers from 1 through 8 are valid values. Values outside this 


range are ignored. 


Example 
See highlight_dw_fkey_label. 
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64.4 Program and User Traces 


Unless their sizes are increased, Program Trace and the User Traces retain a 
maximum of 4096 characters, equivalent to four full screens when every character 
space is used. (See Section (B)2. below on increasing the size of trace buffers.) 
When a buffer’s limit is reached, new characters written to the end of the buffer 
force out the same number of characters from the beginning of the buffer. The 
prompt line is not part of these buffers. Messages are appended to the end of the 
buffers. In Freeze mode you may scroll through the buffer using the cursor keys. 


You write messages to the User Traces only by using C routines. The Run-mode 
softkeys for User Traces—USER TR, TRACE 1, TRACE 2, TRACE 3, TRACE 4, TRACE 5, 
TRACE 6, TRACE 7—appear when the buffers are used in a program. 


(A) Variables 


There are no extern variables associated exclusively with Traces. 
(B) Structures 


1. Declaring trace buffers. The trace routines that write to any of the trace 
buffers require a pointer to the appropriate trace buffer as input. To point 
to one of the trace buffers, you must first have declared it as a structure. 
The structure that is common to trace buffers is named trace_buf. This 
structure is already declared in a file called trace_buf.h located in the 
ARDIsyslinclude directory. The trace_buf structure contains another 
Structure, trace_buffer_header, which also is declared in the trace_buf.h file. 
(These structures are explained in Table 64-6.) Use the #include 
pre-processor directive to include both declarations in your program. 


There are eight trace buffers available (including the Program Trace), each 
one having its own display screen. All are instances of the trace_buf 
structure. Declare each one you use as an extern struct, as in this example: 


extern Struct trace_buf i}_trbuf; 


The names of all the trace buffers are listed in Table 64-6. 


2. Sizing trace buffers. There is a preprocessor #pragma which allows the user 
to configure the size of the data array in each user trace buffer. The syntax 
is TRACE-NUMBER SIZE TRACE-NUMBER SIZE. ... Trace number 0 
refers to the Program Trace buffer, and trace-number “*” allows all 
trace-buffer arrays to be set at once. All sizes are given in terms of 
four-byte array elements. 
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The example below first sets all trace—-buffer arrays to 16,000 elements, and 
then down-sizes array number 3 to 2,048 elements. 


pragma tracebuf * 16000 3 2048 


When a trace buffer is declared, its array will have the size specified in the 
#pragma tracebuf directive. If the buffer was not referenced in a #pragma 
tracebuf directive, its array size will default to 4,096. The maximum size for 
a trace-buffer array is 16,381 elements. If you specify a size that is too 
small or too large, an error message will be displayed. 
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Table 64-6 


Trace Buffer Structures 


Type 


Variable 


Value (hex/decimal) 


Meaning 


Structure Name: trace_buffer_header 


unsigned short 


unsigned short 


unsigned char 


unsigned char 


unsigned char 


unsigned short 


unsigned short 
unsigned char 


unsigned char 


togicai_end 


logleal_end_wrap_count 


modifler 


color 
enhance 


write_lock 


array_size 
Iine_size 


spare 


Structure Name; trace_buf 


struct trace_buffer_header hdr 


unsigned tong 


64-30 


array (4096} 


0-11/0-4095 


0 
non-zero 


0-f1/0-255 


0-fH10-255 


0-ff 1110-66535 


1000/4096 
0-31/0-63 
0 


Structure of a header for trace buffers. 
Declared as type extern struct. Declared 
automatically If a softkey-entered TRACE action 
Is taken. Contained In the structure of the trace 
buffer. Decfaratlon contained In file named 

HRD isyslinctude/trace_buf.h. Written to by %m 
conversion specifier. 


Because It ls an extern structure, values of 
component varlabies should not be altered 
directly by the user. In some Instances, @.g., 
altering array size, the result could be a crash. 


end of data within the buffer. Maximum value Is 
one less than the array size. 


trace buffer Is not full 

trace buffer Is full. As new lines are written to 
the end of the trace buffer, lines at the beginning 
of the buffer are removed. 


Speolal-character Indicator bit and bit 8 must be 
zero. For other speciflo values and thelr 
meanings, see Table 64-4. 


For specific values and thelr meanings, see 
Table 64-4. 


For specific values and thelr meanings, see 
Table 64-4, 


prevents two processes from writing to the same 
buffer at the same time. Should not be altered 


by user or future accass to the trace buffere 
may be locked out. 


size of buffer; at present only one value 
number of characters In last IIne In buffer 


reserved for future use 


Structure of a trace buffer. Declared as type 
extern struct. Declared automatically If a 
softkey-entered TRACE action Is taken. 
Declaration contained In flle named 
HRDIsyslinclude/trace_buf,h, 


structure of the trace-buffer header described 
above 


array of data words In the buffer 


JUL '90 


64 Display Window _and Trace 


Table 64-6 (continued) 


Type Variable 


Value (hex/decimal) 


Meaning 


Structure Name: prog_trbuf 


Struct trace_buffer_header hdr 


unsigned tong array {4096) 
Structure Name: 11_trbuf 


struct trace_buffer_header hdr 


unsigned tong array [4096] 
Structure Name: 12_trbuf 


struct trace_buffer_header hdr 


unsigned tong array [4096] 


tructure N : (3_trbuf 


struct trace_buffer_header hdr 
unsigned long array (4096) 


Structure Name: 14 _trbuf 


struct trace_buffer_header hdr 


unsigned long array [4096] 
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Structure of the Program Trace buffer, an 
instance of the trace_buf structure declared In 
flle named HRDisyslinclude/trace_buf.h. 
Declared as type extern struct trace_buf. 
Declared automatically If a softkey-entered 
TRACE action Is taken. Writing to this buffer 
makes the Run-mode PROG TR softkey appear, 


structure of the trace-buffer header described 
above 


array of data words In the buffer 


Structure of one of seven user trace buffers, an 
Instance of the trace_buf structure declared In 
fille named HADisys/include/trace_buf.h. 
Declared as type extern struct trace_buf. 
Writing to this buffer causes the Run-mode 
TRACE 1 softkey appear. 


structure of the trace-buffer header described 
above 


array of data words In the buffer 


Structure of one of seven user trace buffers, an 
Instance of the trace_buf structure declared In 
flle named HRO/sys/include/trace_buf.h. 
Declared as type extern struct trace_buf. 
Writing to this buffer causes the Run-mode 
TRACE 2 softkey appear. 


structure of the trace-buffer header described 
above 


array of data words in the buffer 


Structure of one of seven user trace buffers, an 
Instance of the trace_buf structure dectared In 
file named HRDisyslinciude/trace_buf.h. 
Declared as type extern struct trace_buf. 
Writing to this buffer causes the Run-mode 
TRACE 3 softkey appear. 


structure of the trace—-buffer header described 
above 


array of data words In the buffer 


Structure of one of seven user trace buffers, an 
Instanoe of the frace_buf structure declared In 
flle named HAD/sys/include/trace_buf.h. 
Declared as type extern struct trace_buf. 
Writing to this buffer causes the Run-mode 
TRACE 4 softkey appear. 


structure of the trace-buffer header described 
above 


array of data words in the buffer 
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Table 64-6 (continued) 


Type Variable Value (hex/decimal) Meaning 
Structure Name: 15_trbuf Structure of one of seven user trace buffers, an 


Instance of the trace_buf structure declared in 
flle named HAD/syslinclude/trace_but.h. 
Deciared as type extern struct trace_buf. 
Writing to this buffer causes the Aun-mede 
TRACE 5 softkey appear. 


struct trace_buffer_header hdr structure of the trace-buffer header described 
above 

unsigned long array [4096] array of data words in the buffer 

Structure Name: 1I6_trbuf Structure of one of seven user trace buffers, an 


instance of the trace_buf structure declared in 
fille named HAD/sys/include/trace_buf.h. 
Declared as type extern struct trace_buf. 
Writing to this buffer causes the Run-mode 
TRACE 6 softkey appear. 


Struct trace_buffer_header hdr structure of the trace-buffer header described 
above 
unsigned long array [4096] array of data words In the buffer 
tr re Name: I7_trbuf Structure of one of seven user trace buffers, an 


Instance of the trace_buf structure declared In 
file named HAD/systinclude/trace_buf.h, 
Declared as type extern struct trace_buf, 
Writing to this buffer causes the Run-mode 
TRACE 7 softkey appear. 


struct trace_buffer_header hdr structure of the trace-buffer header described 
above 
unsigned Jong array (4096} array of data words In the buffer 


(C) Routines 


Most routines defined below are valid for either the Program Trace or the user 
traces. One, however, applies to the user traces only, set_utrace_fkey_label 
allows the programmer to modify the current softkey labels for the user traces. 


The other four trace routines—tracec, tracef, stracef, and traces—apply to both 


the Program Trace and the user traces. The softkey TRACE action is built on 
the tracef routine. 
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The first argument in three of these trace routines is the address of the trace 
buffer into which you want output written. Each time you call a trace routine, 
tracef for example, variables in the named trace-buffer structure are updated. 
Those variables which store attributes are updated when the %m conversion 
specifier is used in the tracef routine parameter. ‘When %m is not present, the 
routine applies the attributes currently stored in the color, modifier, and enhance 
variables. 


The second argument in all four of these trace routines is the character, string, 
or format pointer to the data that will be written to the selected trace buffer. 


The ¢tracef routine allows you to add attributes to messages on the Program 
Trace screen and User Traces. These attributes are listed in Table 64-4. 


Each trace operation appends output to the end of the trace buffer. You may 
not use the pos_cursor routine to position the cursor on any trace screen. New 
lines (or blank lines} may be generated via the “\n” nonliteral. Put the “\n” 
nonliteral at the end of the string to generate a leading blank line on the 
selected trace screen: 


tracef(&prog_trbuf, “This trace message will generate a leading biank line.\n"); 


During real-time display, this line moves just ahead of the freshest trace message 
and continuously overwrites the oldest one. If you put the “\n” sequence at the 
beginning of the format string, no leading blank line will help you distinguish 
new messages from the old: 


tracef(&prog_trbuf, “\nThis message will not generate a leading blank line.”); 


tracec 
Synopsis 
extern void tracec(trace_buffer_ptr, character); 


extern struct irace_buf * trace_buffer_ptr; 
const char character; 


Description 
The tracec routine outputs a single ASCII character to the trace screen 
indicated. 


Inputs 


The first parameter is a pointer to the trace buffer into which the character will 
be written. 


For the second parameter, see the disp/ayc routine. 
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Example 


In this instance, output will be written to the Program Trace screen. 


{ i 
Hinclude <trace_buf.h> 
extern struct trace_buf prog _trbuf; 
) 
LAYER: 2 
STATE: display_to_prog_tr 
CONDITIONS: KEYBOARD * " 
ACTIONS: 
{ 
tracec(&prog_trbuf, ‘a’); 
tracec(&prog trbuf, ‘\n’); 
tracec(&prog_trbuf,65); 
tracec(&prog trbuf, ‘\n'); 
tracec(kprog trbuf,Ox65); 
tracec(kprog trbuf, ‘\n’); 
tracec(&prog_trbuf,065); 


When the user views the PROG TR screen, the output will look like this: 


mo p> w 


tracef 
Synopsis 
extern Int tracef(trace_buffer_ptr, format ptr, ... ); 


extern struct trace_buf * trace_buffer_ptr; 
const char * format_ptr; 


Description 

The tracef routine writes output to a specified trace screen, under control of the 
string, pointed to by format_ptr,-that- specifies -how subsequent arguments are 
converted for output. If there are insufficient arguments for the format, the 
behavior is undefined. If the format is exhausted while arguments remain, the 
excess arguments are evaluated but otherwise ignored. The ¢racef routine 
returns when the end of the format string is encountered. 


Inputs 

The first parameter is a pointer to the trace buffer into which the output will be 
written. 

For the second parameter, see the displayf routine. Placement of “\n” in the 


format string of a call to ¢racef generates a blank new line on the selected trace 
screen. (In a displayf routine, the newline character does not blank the new 


line.) 
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Attributes are written via the %m conversion specifier to trace_buf.hdr.modifier, 

trace_buf.hdr.color, and trace_buf.hdr.enhance. The attributes are copied from 

these variables into subsequent 32-bit data words in the Program Trace and User 
Traces, Table 64-4 shows the format of this 32-bit word. 


Returns 


The tracef routine returns the number of characters displayed, or a negative 
value if the unit is in freeze mode. 


Example 


This program traces X.29 PAD-control messages in DTE and DCE data packets. 
The letters “DCE” are underlined in the DCE trace lines. 


LAYER: 3 
{ 


#include <trace_buf.h> 

extern struct trace_buf 13_trbuf; 

extern unsigned char * m_packet_info_ptr; 
extern unsigned short m_packet_icn; 
unsigned char pad_ctri_msg; 


STATE: packet_type 
CONDITIONS: DTE DATA Q= 1 
ACTIONS: 


{ 
pad_cirl_msg = m_packet_info_ptr{0]; 
tracef (&t3_trbuf, “DTE LCN; %.3x PAD MSG: %.2x\n", m_packet_lcn, 
pad_ciri_msg); 


} 
CONDITIONS: DCE DATA Q= 1 
ACTIONS: 


pad_cirl_msg = m_packet_info_ptr{0}; 
tracef (&i3_trbuf, “%mDCE%m LCN: %.3x PAD MSG:%.2x\n", 0x04000000L, 
O0x00000000L, m_packet_ten, pad_ctri_msg); 


stracef 


Synopsis 


extern vold stracef(array_ptr, string_ptr); 
unsigned long array_ptr; 
const char * string ptr; 


Description 
The stracef routine is similar to the tracef routine, except that stracef writes 
output to a variable, while tracef writes output to a trace screen, The output is 


under control of the string pointed to by string_ptr that specifies how subsequent 
arguments are converted for output. If there are insufficient arguments for the 
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format, the behavior is undefined. If the format is exhausted while arguments 
remain, the excess arguments are evaluated but otherwise ignored. The stracef 
routine returns when the end of the format string is encountered. 


The stracef routine differs from sprintf in that it generates an array of longs, 
whereas sprintf generates an array of chars. When the Sstracef array is written to 
a trace buffer (or to the Display Window) it carries its predefined attributes 
along with it. An sprintf array, by contrast, will receive the attributes that are 
active in the buffer at the moment. 


At the end of the output string, there will be a null character with the Special 
Character Indicator bit set in its modifier attribute-byte. 


Inputs 


The first parameter is a pointer to the variable into which output will be written. 
The array which will hold output must be declared as a Jong. By allocating 32 
bits for each element, the array may accommodate attributes assigned via the 
%m conversion specifier. Attributes comprise 24 bits of the jong. The preferred 
form of the declaration is unsigned long name [100]. The size and name of the 
array are user-determined. 


For the second parameter, see the displayf routine. 


Example 


This program traces X.29 PAD-control messages for DTE and DCE data 
packets. The resulting trace is identical to the one generated by the example 
under ¢tracef. Note that attributes that are turned on in an stracef array do not 
need to be turned off after the array has been brought, via the %b conversion 
specifier, into a ¢racef format string. 


rans 3 
#include <trace_buf.h> 
extern struct trace_buf 13_trbuf; 
extern unsigned char * m_packet_info_ptr; 
extern unsigned short m_packet_ien; 
unsigned char pad_cirl_msg; 
unsigned long source [4]; 


STATE: packet_type 
CONDITIONS: DTE DATA Q= 1 
ACTIONS: 
stracef (source, “%s", “DTE”); 


} . 
NEXT_STATE: pad_msg_trace 
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CONDITIONS: DCE DATA Q= 1 
ACTIONS: 


stracef (source, “%m%s", Ox04000000L, “DCE’’); 


} 

NEXT_STATE: pad_msg_trace 
STATE: pad_msg_trace 

CONDITIONS: ENTER_STATE 

ACTIONS: 


pad_cirl_msg = m_packet_info_pir{0]; 
tracef (&i3_trbuf, “%b LCN: %.3x PAD MSG: %.2x\n", source, m_packet_Icn, 
pad_ctri_msg); 


} 
NEXT_STATE: packet_type 


traces 
Synopsis 


extern void traces({trace_buffer_ptr, string ptr); 
extern struct trace_buf trace_buffer_ptr; 
const char * string_ptr; 


D inti 
The traces routine writes output to a specified trace screen, under contro! of the 


string that is referenced by string _ptr. The traces routine returns when the end 
of the string is encountered. 


Inputs 


The first parameter is a pointer to the trace buffer into which the output will be 
written, 


For the second parameter, see the displays routine. 


Example 


In this instance, output will be written to the TRACE 1 screen. 


The following entry 


{ 


#include <trace_buf, h> 
extern struct trace_buf I]_trbuf; 


} 


LAYER: 1 
STATE: any 
CONDITIONS: KEYBOARD * * 
ACTIONS: 
{ 
traces(&U_irbuf, “End of test.”); 


) 
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produces the following output on the .TRACE.1 trace screen: 
End of test. 


The following coding produces the same output: 


{ 
#include <trace_buf. h> 
extern struct trace_buf i1_trbuf; 


} 
LAYER: ft 
STATE: any 
CONDITIONS: KEYBOARD * ” 
ACTIONS: 


{ 

const char * string_ptr; 

String pir = “End of test."; 
traces (&il_trbuf, string_ptr}; 


) 


set_utrace_fkey_label 


Synopsis 


extern void set_utrace_fkey_label(trace_buffer, label_ptr); 
unsigned int trace_buffer; 
const char * tabel_ptr; 


Description 


Use the set_utrace_fkey_label routine to modify the labels which identify the 
seven user-trace buffers. The default labels are TRACE 1, TRACE 2, TRACE 3, 
TRACE 4, TRACE 5, TRACE 6, TRACE 7. These labels correspond to the user-trace 
buffer with the same number. There is no Protocol Spreadsheet softkey 
equivalent of this routine. 


Inputs 


The first parameter identifies the user-trace function key whose label is to be 
replaced. Integers from 1 through 7 are valid values. The buffer number must 
correspond to a user-trace buffer that is written to in the program. If it does 
not or if the specified value is out of the valid range, the label is not assigned to 
any softkey. 


The second parameter is a pointer to a null-terminated string, i.e., the label that 
should replace the current one for the specified trace buffer. The label string 
has a maximum length of seven characters. If it has fewer than seven 
characters, it is padded to the right with spaces. If it has more than seven 
characters, only the first seven are used. 
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Example 


In the following example, new labels are assigned to the softkeys for user-trace 
buffers 2 and 3. If you press the USER TR softkey in Run mode, the labels 
TRACE 1 and TRACE 2 should be replaced with FAAME and PACKET. 


{ 


Hinclude <trace_buf.h> 
extern Struct trace_buf 12_trbuf; 
extern Struct trace_buf {3_trbuf; 


} 
LAYER: 1 
STATE: define_labels 
CONDITIONS: ENTER_STATE 
ACTIONS; 


{ 
set_utrace_fkey_label(2, “ FRAME”); 
set_utrace_fkey label(3, “PACKET”); 


} 
NEXT_STATE: write_to_buffers 


STATE: write_to_butfers 
CONDITIONS: KEYBOARD “2" 
ACTIONS: 

{ 


tracef(&l2_trbuf, “Frame Level Information”); 


} 
CONDITIONS: KEYBOARD “3” 
ACTIONS: 


tracef(&l3_irbuf, “Packet Level Information”); 


64.5 Attributes 


Attributes are written to the Display Window and to the trace buffers in 32-bit words 
that include 8 bits of character data (the second-lowest byte) and 24 bits of 
attributes. The format of the 32-bit data word, given in Table 64-4, is the same for 
the Display Window and for the trace buffers, 


In displayf routines, the %m conversion specifier writes input to window_color and 
window_modifier variables. These variables are then copied into data words written to 
the Display Window by string pointers in this.and subsequent displayf routines. See 
Figure 64-1. 


In tracef routines, the %m conversion specifier writes input to the 
trace_buffer_header structure for a particular user—trace buffer. The header is then 
copied into each data word written to the particular user buffer by string pointers in 
this and subsequent fracef routines. See Figure 64-2. 
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(A) Applying Attributes As Data Is Buffered 


There are two ways an attribute may be assigned to a character in the Display 
Window. One way uses the %m conversion specifier to assign attributes to the 
window_color and window_modifier variables. This program, for example, 
includes a displayf routine that uses the %m conversion specifier to write 
underlined data to the Display Window: 


STATE: apply_attribute_to_window_color_vartable 
CONDITIONS: ENTER_STATE 
ACTIONS: 
{ 


pos_cursor (1,0); 
displayf (“%mThis data is underlined in the Display Window." , 0x04000000L) ; 


The chart in Table 64-4 shows the hex value 04000000L in the “input” column 
alongside the underline attribute. This means that when the value 0x04000000L 
is input to the conversion specifier %m, an underline attribute is applied to the 
current displayf string and any that follow until the attribute is turned off. The 
underline attribute actually is applied to the external window_color variable. See 
Table 64-2. The window_color and window_modifier variables lend their 
attributes to every character that is written in a format string to the Display 
Window. In Run mode if the user presses the softkey for DSP WND, he will see 
his underlined string. Subsequent characters or strings written to the Display 
Window also will be underlined. . 


The same attribute could be applied to a string in any of the user-trace buffers, 
as follows: 


{ 
#include <trace_buf.h> 
extern struct trace_buf 11_trbuf; 


) 
STATE: apply_attribute_to header 
CONDITIONS: ENTER_STATE 
ACTIONS: , 


{ 
tracef (&il_irbuf, “%mThis data is underlined.”, 0x04000000L); 


} 


Only the header for the TRACE 1 display is affected by this %m conversion. 
Only the TRACE t buffer is written to. When other trace buffers are 
subsequently written to, the strings will not receive underlining as a result of the 
attributes applied above to the TRACE 1 header. 
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displayf(“%mDATA” , 0x08100000L); 
| 
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display_window_buffer [3] 


-_—— 


display_window_buffer [1088] 


Figure 64-1 When a dispiayf routine is called, the attributes assigned via the %m 
conversion specifier are stored in two extern variables, accessible to the user. Both 
color and enhance allributes are contained in window_color. The low byle in 
window_color indicates the color; the high byte contains enhancements. In this 
example, the following attributes will be assigned to characters written to the 
Display Window: reverse~image enhancement, green-on-black color, and ASCII 
font. Before a character is wrillen to the Display Window, it is combined in a long 
with lis aliribules, as mapped in the figure. 
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tracef(&i1_trbuf, “%MDATA", 0x981Q00Q0L); 
Al gO 
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M_trbuf.array [4096] 


Figure 64-2 When a tracef routine is calied, the attributes assigned via the %m 
conversion specifier are stored in three variables in the trace-buffer header of a 
designated buffer. In this example, (/_trbuf. hdr holds the following attributes: 
reverse-image enhancement, green-on-black color, and ASCII font. Before a 
character is written to the buffer, it is combined in a /ong with ils altributes, as 
mapped in the figure. 


64-42 JUL °90 


64 Display Window and Trace 


JUL "90 


(B) Applying Attributes to Buffered Data 


The Display Window is an array of 1,088 fong integers, each including one byte 

of character data: and three bytes of attributes. The character data is generated 

by strings in display routines. The attributes for each character are derived from 
the current window_color and window_modifier values at the time the character 

is written to the display-window buffer. 


Once the data word is written to the buffer as an element in the array, it can be 
accessed and written to—and therefore changed—the same as any other location 
in memory. In the example: that follows; a string is written to the Display 
Window without underlining. Then, as a result of a keyboard input from the 
operator, the first 32-bit word in the string (containing the first character, the 
letter “T”) is given a new value that includes the underline attribute. 


{ 
extern unsigned long display_window_buffer [1088]; 
extern struct 
{ 
unsigned char mpm; 
unsigned char cpm; 
} 
display_window_index_buffer{17]}; 
} 
STATE: apply_attribute_directly_to_display_window 
CONDITIONS: ENTER_STATE 
ACTIONS: 
{ 
pos_cursor(1,0); 
displayf (“This data is not underlined.”); 


} 
CONDITIONS: KEYBOARD * * 


ACTIONS: 
{ 
display _window_buffer[64] = ((display_window_buffer{64] & ~Ox04000000L) | 
0x04000000L); 
display_window_index_buffer{I].mpm ++; 


} 


Incrementing display_window_index_buffer.mpm is necessary to alert the 
processor on the CPM card (containing the disptay-controller software) that the 
program has changed the contents of the Display Window. Refer to Table 64-3 
for an explanation of this structure. 


The bitwise anding and oring in the example are necessary if you want to change 
certain bits in the word without affecting others. Note that the value whose 
complement (-) is anded with display_window_buffer element #64 is the “mask” 
for the underline attribute in Table 64-4; and the value to the right of the or 
operator (|) is the “input” value for the underline attribute. 
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Table 64-7 


Conversion Specifiers 


Specifler 


Argument type 


Conversion Type 
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%b 


%l 
%o 
%#C 


ed 
%ld 
%H 


%*m 


%S 


Integer-array polnter 


Integer 
unsigned character 


unsigned character 


integer 
integer 


character-array polnter 


integer 


Integer 
Integer 
Integer 


Integer 


Integer 


character-array polnter 


character-array pointer 


Integer 
Integer 


integer 


integer 


array of long Integers. 2nd byte of each 
long is displayed as character. 1st, 3rd, and 
4th bytes Interpreted ae attributes. Array 
begins at pointer, ends at element contalning 
null character and Speolal Character bit = 1. 


signed decimal representing 15-bit value 
unsigned character 


newline character displayed as + rather than 
acted on 


signed decimal representing 15-bit value 
signed decimal representing 31-bit value 


character array Indicated by argument 
appears as small hex characters. 
(Precision as to number of characters 
becomes length of the array, overriding 
usual nul-termination of strings.) 


fong Integer not displayed or printed, but 
written to attribute header-variable for Display 
Window or for one of the trace buffers 


unsigned octal representing 16-bit value 
unsigned octal representing 32-bit value 


unsigned octal representing 16-bit value, 
preceded by 0 


unsigned octal representing 32-bit value, 
preceded by 0 


unsigned hexadecimal (fower-case letters) 
representing 32-bit value, with a minimum 5 
digits displayed and a colon between the 4 
right-hand digits and the 1-4 left-hand digits. 
Useful for displaying CPU segment number and 
offset, 


array of characters beginning at polnter and 
ending at null terminator or at array-length 
precision, whichever occurs first 


newline character displayed as ‘+ rather than 
acted on 


unsigned decimal representing 16-bit value 


unsigned decimal representing 32-bit value 


hex characters (example: ®"s ) representing 
16-bit value 


hex characters (example: °r®s%o's } 
representing 32-bit value 
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Specifler Argument type Conversion Type 
%X Integer unsignad hexadecimal (lower-case letters) 
representing 16-bit value 
%Ix Integer unsignad hexadecimal (lower-oase letters} 
representing 32-bit value 
%HX Integer unsigned hexadecima! (lower-case letters) 
representing 16-bit value, preceded by 0x 
HX Integer unsigned hexadecimal (lower-case letters) 
representing 32-bit value, preceded by 0x 
%X Integer unsigned hexadecimal (upper-case letters) 
representing 16-bit value 
IX Integer unsigned hexadecimal (upper-case letters) 
representing 32-bit value 
%#X Integer unsigned hexadecimal (upper-case letters) 
representing 16-bit value, preceded by 0x 
HX Integer unsigned hexadecimal (upper-case letters) 
representing 32-bit value, preceded by 0x 
%\n none displays an 'y 
%% none displays a % 
64.6 Protocol Trace Buffers 


There are two Protocol Trace buffers, one dedicated to Layer 2 and the other to 
Layer 3 data. Run-mode softkeys for accessing these traces—PROTOCL, L2TRACE, 


and L3TRACE—appear when personality packages are loaded in at Layers 2 and 3. 


The prompt line is not part of these buffers. 


The size of each Protocol Trace buffer is 65,536 bytes. Of this total, two bytes are 
dedicated to the buffer header and two bytes to the trailer. The usable size of a 
Protocol Trace buffer, therefore, is 65,532 bytes. When a buffer’s limit is reached, 
new characters written to the end of the buffer force out the same number of 
characters from the beginning of the buffer. In Freeze mode you may scroll through 
the buffer using the cursor keys. 


You cannot write directly to the Protocol Trace buffers. Monitor the position within 
the buffers, as well as the wrap count, using the variables and structures discussed 
below. 


(A) Variables 


The addresses of the variables in Table 64-8 identify the physical location of the 
beginning and end of each Protocol Trace buffer. The beginning position is at 
the first data byte in the buffer. The end is just after the last data byte. 
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Table 64-8 
Protocol Trace Buffer Variables 


Type Variable Value (hex/decimal) Meaning 


extern unsigned char l2pp_trbuff First data byte In the Layer 2 
Protocol Trace buffer. Address 
of this varlable—segment 
number plus offset—will Indicate 
the physical location of the first 
data byte, two bytes from the 
beginning of the buffer, Line 
Setup configured for emulate or 
monitor mode. 


extern unsigned tong l2pp_trbuff_end First byte In the two-byte traller 
of the Layer 2 Protocol Trace 
buffer—l.e., after the last data 
byte. Address of this 
varlable—segment number plus 
offset—will indicate the physical 
location of the end of the data 
area, hexadecimal FFFE bytes 
from the beginning of the 
buffer. Line Setup configured 
for emulate or monitor mode. 


extern unsigned char I3pp_trbuff First data byte In the Layer 3 
Protocol Trace buffer. Address 
of this varlable—segment 
number plus offset—will Indicate 
the physical location of the first 
data byte, two bytes from the 
beginning of the buffer. Line 
Setup conflgured for emulate or 
monitor mode. 


extern unsigned tong 3pp_trbuff_end First byte in the two-byte traller 
of the Layer 3 Protocol Trace 
buffer—l.e., after the last data 
byte. Address of this 
varlablea—segment number plus 
offset—will Indicate the physical 
location of the end of the data 
area, hexadecimai FFFE bytes 
from the beginning of the 
buffer, Line Setup configured 
for emulate or monitor mode. 
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(B) Structures 


The structure variables in Table 64-9 contain the high and low bytes of a 
beginning and ending offset and wrap-count in the Layer 2 and Layer 3 
Protocol Trace buffers. Create a logical beginning (or ending) offset within a 
buffer by combining the two offset-variables relating to a beginning (or ending) 
position into a single, two-byte offset. Add the resulting offset to the address of 
13_trbuff to identify the physical address of a logical location. 


The example below uses #define preprocessor directives for determining 
beginning and ending offsets in the Layer 3 Protocol Trace buffer. When 
get_l3pp_value_end is encountered in a program, for example, each of the two 
“end” offset-variables is cast into a fong and, if necessary, shifted left to its 
appropriate position in an offset. Then the two variables are added together. 


H#define get_i3pp_value_begin 
(((unsigned long) (i3pp_trbuff_ctt. begin_off_hi) << 8) + 
((unsigned long) (t3pp_irbuff_ct!. begin _off_io))) 


#define get_{3pp_vaiue_end 
(((unsigned long) (i3pp_trbuff_ctt.end_off_hi) << 8) + 
((unsigned long) (i3pp_trbuff_ctl.end_off_io)}) 


When the ending offset, in this example, is added to the address of /3_trbuff, 
the result is the address of the /ogical end in the buffer: 


unsigned long end_address; 
end_address = &i3_trbuff + get_I3pp_value_end; 


You may also use the offsets and wrap counts to determine how much data is 
currently in the buffer. Include the wrap count in the high two bytes of a 
four-byte offset. Then subtract the beginning offset from the ending offset. 


define get_l3pp_value_begin 

(((unsigned iong) (I3pp_trbuff_ctt. begin_wrap_hi) << 24) + 
((unsigned long) (\3pp_trbuff_ctt. begin_wrap_lo) << 16) + 
((unsigned long) (13pp_trbuff_ctl. begin_off_hi) << 8) + 
((unsigned long) ({3pp_trbuff_ctt. begin_off_lo))) 


#define get_i3pp_value_end 

(((unsigned long) (l3pp_trbuff_cel.end_wrap_hi) << 24} + 
({unsigned long) ((3pp_trbuff_ctl.end_wrap_lo) << 16) + 
((unsigned long) ({3pp_trbuff_ct!.end_off_hi} << 8) + 
((unsigned long) (i3pp_trbuff_ctt.end_off_!o)}}) 


unsigned long end, begin, count; 
end = get_(3pp_value_end; 

begin = get_l3pp_vaiue_begin; 
count = end — begin; 
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Table 64-9 


Protocol Trace Buffer Structures 


Type 


Variable 


Value (hex/decimal) 


Meaning 


Structure Name: Ipp_trbuff_cti 


unsigned char 


unsigned char 


unsigned char 


unsigned char 


unsigned char 


unsigned char 


unsigned char 


unsigned char 


begIin_aff_hl 


begin_off_lo 


begin_wrap_hl 


begin_wrap_lo 


end_off_hl 


end_off_lo 


end_wrap_hl 


end_wrap_lo 


Structure Name: I2pp_trbuff_ctl 
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0-ff10-255 


0-1/0-255 


0-1110-255 


0-ff/0-255 


0-ff10-255 


0-f110-255 


0-ff10-255 


0-11/0-255 


Declared as type struct. The varlables contalned 
In this structure monitor logical location In a 
Protocol Trace buffer. Reference structure 
varlables as follows: /pp_trbuff_ct!,begin_off_hi. 


High byte of a 2-byte offset from the physical 
beglnning of the Protocol Trace buffer to a 
fogica! beginning In the buffer. Range of the 
two-byte offset Is 2 through hexadecimal FFFE. 


Low byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical beginning in the buffer. Range of the 
two-byte offset Is 2 through hexadecimal FFFE. 


High byte of a 2-byte count of the number of 
tlmes a fogica! beginning has wrapped through 
the Protocol Trace buffer, 


Low byte of a 2-byte count of the number of 
tImes a logical beginning has wrapped through 
the Protocol Trace buffer. {t will have a value of 
zero only once. Once the count reaches 
hexadecimal FFFF, it will wrap to one. 


High byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical end in the buffer. Range of the two-byte 
offset Is 2 through hexadecimal FFFE. 


Low byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical end In the buffer. Range of the two-byte 
offset is 2 through hexadecimal FFFE. 


High byte of a 2-byte count of the number of 
tImes a /ogical end has wrapped through the 
Protocol Trace buffer. 


Low byte of a 2-byte count of the number of 
tlmes a /ogicaf end has wrapped through the 
Protocol Trace buffer. It will have a value of zero 
only once. Once the count reaches hexadecimal 
FFFF, It will wrap to one. 


An Instance of the Ipp_trbuff_ct! structure, 
declared as type extern struct Ipp_trbuft_ctl. 
The varlables contalned In this structure monitor 
logical location In the Layer 2 Protocol Trace 
buffer. Has the same structure as 
Ipp_trbuff_ct. Reference structure varlables as 
follows: /i2pp_trbuff_cti.begin_oft_h. 
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Table 64-9 (continued) 


Type Variable. Value (hex/decimal) Meaning 
Structure Name: I3pp_trbuff_ctl An instance of the /pp_trbu/ff_ct! structure, 


declared as type extern struct ipp_trbuft_ctl. 
The varlables contained [n this structure monitor 
logleat location In the Layer 3 Protocol Trace 
buffer. Has the same structure as 
Ipp_trbuff_ct!, Reference structure varlables as 
follows: /3pp_trbuff_cti.begin_off_h. 


(C) Routines 


The set_ltrace_fkey_label routine allows the programmer to modify the current 
softkey labels for the Layer 2 and 3 Protocol Traces. There is no Protocol 
Spreadsheet softkey equivalent of this routine. 


set_Itrace_fkey_ label 


Synopsis 


extern void set_ltrace_fkey_label(layer, tabet_ptr); 
unsigned int layer; 
const char * label_ptr; 


ripti 


Use the set_ltrace_fkey_label routine to modify the labels which identify the two 
Protocol Trace buffers. The default labels are L2ETRACE and L83TRACE. These 
labels correspond to the Layer 2 and 3 Protocol Traces. 


Inputs 


The first parameter identifies the Protocol Trace function key whose label is to 
be replaced. Integers from 1 through 7 are valid values. The number must 
correspond to a layer package which is currently loaded into the INTERVIEW. 
If it does not or if the specified value is out of the valid range, the label is not 
assigned to any softkey. 


The second parameter is a pointer to a null-terminated string, i.e., the label that 
should replace the current one for the specified Protocol Trace. The label string 
has a maximum length of seven characters. If it has fewer than seven 
characters, it is padded to the right with spaces. If it has more than seven 
characters, only the first seven are used. 


JUL '90 64-49 


INTERVIEW 7000 Series Advanced Programming: ATLC-107-951-108 


Example 


In the following example, the X.25 Layer 2 and Layer 3 protocol packages have 
been loaded via the Layer Setup screen. New labels are assigned to the softkeys 
for both Protocol Traces. If you press the PROTOCL softkey in Run mode, the 
labels L2ETRACE and L3TRACE should be replaced with X25 FRM and X25 PKT. 


LAYER: 1 
STATE: define_labels 

CONDITIONS: ENTER_STATE 
ACTIONS: 
{ 
set_ltrace_fkey_label(2, “X25 FRM"); 
set_lirace_fkey_label(3, “X25 PKT”); 
} 
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65 Counters, Timers, and Accumulators 


65.1 Counters 


The translator declares the following structure for counters that are entered as softkey 
tokens on the Protocol Spreadsheet: 


Struct counter_struct 


{ 


unsigned long current; 

unsigned long last; 

unsigned long maximum; 

unsigned long minimum; 

unsigned short sample_count; 

unsigned tong total_high; 

unsigned short total_tow_low; 

unsigned short total_low_high; 

unsigned short oui_of_range; 

unsigned short changed; 

unsigned tong prev; 

unsigned long old; 
}: 
struct counter_struct counter_name={0,0,0,-Oul); 
The first eight counter variables in the structure are used to calculate statistical values 
whenever the counter is sampled. See Table 65-1. Three of the 
variables—counter_name,current, counter_name.prev, and counter_name.old—come 
into play each time the counter is incremented, decremented, or set to a particular 
value. 


Counters are internal program variables and counter interrupts are strictly 
program-generated signals, so the C programmer is free to ignore this structure and 
maintain counts and statistics in a different way. Please note, however, that the 
68010 CPU expects this counter structure when it polis the 80286 periodically for 
statistical values to display in columns on the tabular and graphic stats screens. 


(A) Current, Previous, and Old Values 


When a counter is incremented, decremented, or set to a specific value on the 
Protocol Spreadsheet, the program does not signal a counter_name_change 
interrupt automatically. First it verifies that the new value of the counter really 
is a change from the previous value. See Table 65-2. For this comparison, the 
program needs to maintain two variables, counter_name.current and 


counter_name.prev. 
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Table 65-1 
Counter Structures 


Type 


Variable 


Meaning 


Structure Name: counter_struct 


unsigned fong 
unsigned long 
unsigned long 
unsigned fong 
unsigned short 


unsigned tong 
unsigned short 


unsigned short 
unsigned short 


unsigned short 
unsigned long 


unsigned long 


current 

last 
maximum 
minimum 
sample_count 


total_high 
total_low_low 


total_low_high 
out_of_range 


changed 
prev 


old 


Structure of a counter. Declared as type struct. 
Declared automatically If a program counter Is 
used. Program counters assigned to structure 
as follows: struct counter_struct counter_name. 
Reference a structure varlable as follows: 
counter_name.current, 


This value of the counter Is acted on direotly by 
program actions. 


Last aampled value; displayed on the tabular 
statistics screen. 


Maximum value of afl samples; displayed on the 
tabular statistlos screen. 


Minimum value of all samples; displayed on the 
tabular statistles screen. Should be Initlalized as 
~Oul. 


Number of samples. 
High four bytes of an elght-byte counter total. 


Low two bytes of an elght-byte counter total. 
This two-byte variable counts to 65,535, 


Bytes 3 and 4 of an elght-byte counter total. 


Number Is out of range, elther Incramented 
beyond the range or decremented betow 0; 
should not be factored Into averages. 


For future uss. 


When converting a counter action to C, the 
translator compares prev with current to 
determine whether counter has changed. Then 
prev Is updated to current and 
counter_name_change Is signaled. 


When converting a counter conditlon to C, the 
translator compares o/d with current to 


-determine whether true condition is new 


(transitional). After program logic has examined 
counter, o/d is updated to prev. 


Here, for example, is the C translation of the simple action COUNTER example 


SET 5. 


counter_example.current = 5; 


if (counter_example, prev [= counter_example. current) 


{ 


counter_example. old = counter_example. prev; 
counter_example. prev = counter_example. current; 


signal (counter_example_change); 


} 
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Table 65-2 ; ; 
Counter Variables 


Type Variable Meaning 


extern event counter_name_change True when the named counter Is 
Incremented, decremented, or 
set to new value. This event will 
not be triggered untess a 
spreadsheet condition names 
the counter. Line Setup 
configured for emulate or 
monitor mode. 


It is clear from the translation that the variable counter_example.prev is used to 
limit the number of counter_example_change interrupts to those cases where the 
current value of the counter really has changed. 


What is counter_name.old used for? We will preface the answer by citing the 
behavior of the counter in the following spreadsheet example. 


STATE: threshold_condition 
CONDITIONS: KEYBOARD “* ” 
ACTIONS: COUNTER spacebar INC 
CONDITIONS: COUNTER spacebar GE 7 
ACTIONS: ALARM 


Each time you press the space bar while this program is running, the counter will 
increment, but no matter how many times you press the space bar the alarm will 
only sound once. It will sound on the seventh keystroke, the first time the 
counter is greater than or equal to 7. If the program had a decrement or set 
action that lowered the counter to less than 7, the alarm would sound again 
when the counter reached the 7 threshold. 


The translator accomplishes this threshold condition by coding the waitfor clause 
as follows: 


counter_spacebar_change && {1 (counter_spacebar,old >= 7)) && (counter_spacebar, current >= 7): 


Since counter_spacebar.prev was used (and then updated to “current”) in the if 
statement that sent the counter_spacebar_change interrupt, the “old” value is 
required in the waitfor condition. to insure a “transitional” or “threshold” 
counter condition. 
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(B) 


(C) 


Sampling a Counter 


Here is the translator’s version of a counter sample action: 


counter_name.last = counter_name. current; 
if (counter_name. current > counter_name.maximum) 


{ 


counter_name, maximum = counter_name.current; 


} 


if (counter_name.current < counter_name.minimum) 


counter_name.minimum = counter_name. current; 


} 


counter_name.sample_countt+; 


{ 
unsigned long temp; 
temp = (counter_name.current & Ox0000ffff) + counter_name.total_low_low; 
counter_name.total_low_low = temp; 
temp = (counter_name.current >> 16) + counter_name.total_low_high + (temp >> 16); 
counter_name.total_low_high = temp; 
counter_name.total_high += temp >> 16; 


} 


counter_name.current = 0; 


In order to establish an average value for ail samples, a grand total for current 
values at the time of each sampling must be maintained. Since an ordinary 
INTERVIEW current counter is 32 bits, the counter that maintains the grand 
total of current counts must be larger (64 bits). There is no data type this large 
in C, and so the “total” counter is distributed among three variables and the 
somewhat complicated coding involving the temp variable is required to add the 
current counter to this composite counter. 


Updating the Statistics Screen 


The CPM polls the MPM continuously to see if data is available to be output to 
the printer or the plasma display. This data includes character data, trace data, 
prompts, and values to be posted to the statistics screens. 


In order to know where on the statistics screens the values for the particular 
counters (and timers and accumulators) should be placed, the 68010 CPU on 
the CPM needs some help from the program (that is, from the MPM). This 
help is in the form of a “stat message” that the translator (or the programmer) 
codes once at the beginning of the program. The stat message is a structure that 
the MPM sends to the CPM. See Table 65-3. The stat message says, in effect, 
“Here is the address of a counter structure. When you access this structure 
during the running of the program in order to pull out the current, last, 
maximum, minimum, total, and sample-count values, display those values on the 
row of the tabular stats screen where the user has typed spacebar” (for 
example). 
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Table 65-3 


Counter, Timer, and Accumulator Structures 


Type Variable Value (hex/decimal) 


Meaning 


truct i stat_msg 


unsigned short op_type 0a00/2560 

unsigned short type 0 
0100/256 
0200/512 

unsigned long object_name 

unsigned long object_address 


Structure of a stat message. A stat message Is 
sent once for each named counter, tlmer, or 
accumulator. Declared as type struot. Declared 
automatically If a softkey-entered COUNTER Is 
used as a condition, or If softkey-entered 
COUNTER, TIMER, or ACCUMUL action fs taken. 
Program stat messages assigned to structure as 
follows: struct stat_msg name, You must 
assign values to the elements of the structure. 
Reference a structure varlable as follows: 
name.type. 


Register statistics objects fram the MPM to the 
CPM. Other values and meanings for future use. 


accumulator 
counter 
timer 


The MPM (80286) address of a counter, timer, 
or accumulator name, converted to CPM (68010) 
format. To get an object_name address, enter: 
name .object_name = 

gat_68k_phys_ addr(“name_of_counter”); 


The MPM {80286) address of a counter, timer, 
or accumulator structure, converted to CPM 
(68010} format. To get a struoture address for 
a counter, enter: name,object_address = 
get_68k_phys_addr(&counter_name_of_counter), 


Here is a C program that causes the current value of a counter named “key” to 
increment on the tabular-statistics screen each time an ASCII-keyboard key is 


struck. 


{ 
struct 
{ 
unsigned short op_type; 
unsigned short type; 
unsigned long object_name; 
unsigned tong object_address; 
} stat_msg; 
extern unsigned long get_68k_phys_addr(); 
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Struct counter_struct 
{ 
unsigned long current; 
unsigned tong last; 
unsigned long maximum; 
unsigned long minimum; 
unsigned short sampie_count; 
unsigned long total_high; 
unsigned short total_low_low; 
unsigned short total_low_high; 
unsigned short out_of_range; 
unsigned short changed; 
unsigned long prev; 
unsigned tong oid; 
}: 
Struct counter_structure counter_key; 
extern fast_event keyboard_new_key; 
} 
STATE: update_stat_screen 
{ 
stat_msg.op_type = 2560; 
stat_msg. type = 256; 
Stat_msg. object_name = get_68k_phys_addr (“key”); 
stat_msg.object_address = get_68k_phys_addr(&counter_key); 
send Stat_message(&stat_msg); 
wailfor 
{ 
keyboard_new_key: 
{ 
counter_key.currenttt+; 


} 
} 


The variable stat_msg.object_name is a pointer to the name of the counter that 
the user has entered on the protocol spreadsheet. The program gives this name 
to the CPM, and expects the CPM to locate the name among the names that 
the user has entered on the tabular or graphic statistics menu. The delivery to 
the CPM of a pointer to the stats-menu name and a pointer to the counter 
structure is the purpose of the stat message. The message allows the CPM to 
correlate a line on the statistics results screen with an actual program counter (or 
timer or accumulator). 
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NOTE TO C PROGRAMMERS: When the translator creates a 
counter variable it adds the prefix counter_ to the spreadsheet 
name, but the programmer who is working primarily in C and is 
not making use of spreadsheet counters can name the counter 
any way he wishes, with or without the prefix. Similarly, the 
String that is communicated to the CPM in stat_msg.object_name 
(“key” in the example above) must agree with the name on the 
stats menu, but it need not bear any resemblance to the name of 
the counter structure. 


NOTE ALSO: In most of the examples in this manual, we have 
not bothered to declare routines since it is not necessary. In the 
absence of a declaration, the compiler assumes that the routine is 
externa! and that it returns an integer. In nearly all cases, this 
assumption works. get_68k_phys_addr() returns a long, however, 
and must be declared. 
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65.2 Timers 


The translator declares the following structure for timers that are entered as softkey 
tokens on the Protocol Spreadsheet: 


Struct timer_siruct 


{ 

unsigned long current; 

unsigned long last; 

unsigned long maximum; 

unsigned long minimum; 

unsigned short sample_count; 

unsigned long totat_high; 

unsigned short total_tow_low; 

unsigned short total_low_high; 

unsigned long start_tick_value; 

unsigned short running; 

unsigned short changed; 
} 
There are no timer conditions in the software (since timeouts provide the 
time-triggering function), and therefore all of the variables in the structure serve as 
data for the CPM when it updates the stats screens. See Table 65-4. A stat message 
must be sent so the CPM can correlate a line on the statistics results screen with the 
correct program timer. The stat message is documented in the previous section on 
counters. The timer stat message is different only in respect that the stat_msg.type 
element should be set to 512 instead of 256. 


Timer restart, continue, and stop actions are explained in this section. The clear 
action is simply a matter of changing the elements in the structure to zero (except for 
timer_name,.minimum, which becomes the one’s complement of zero). 


(A) Time Ticks 


Time ticks are timed increments of either of two hardware counters in the 
INTERVIEW. The programmer can select which of the two timing mechanisms 
to use for a given timer. 


One tick-counter is on the FEB card and is used to time~stamp incoming data 
and EIA leads. The intervals between ticks is determined on the FEB Setup 
menu. Ticks can be enabied/disabled on the same menu. The current value of 
this counter is available in a variable called //_tick_count. See Table 65-5. The 
current value always reflects the number of ticks since the program entered Run 
mode. The number of ticks may or may not equate to the amount of time in 
Run mode, since ticks are also encoded in playback data and the playback rate 
is subject to “local conditions” such as playback speed and idle suppression. 


FEB time ticks are the most precise timing mechanism in that they have a 
resolution to 10 microseconds. They also represent the most durable method of 
timekeeping, since they preserve the original data timings even during playback. 
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Timer Structures 


Vaiue (hex/decimal) 


Meaning 


Type Variable 
Structure Name; timer_struct 
unsigned long current 
unsigned long tast 
unsigned tong maximum 
unsigned long minimurn 


unsigned short 
unsigned long 

unsigned short 
unslgned short 


unsigned fong 


unsigned short 


unsigned short 


sample_count 
total_high 
total_low_low 
total_tow_high 


start_tick_value 


running 


changed 


Structure of a timer. Declared as type struct. 
Declared automatically If a program timer Is 
used. Program timers assigned to structure as 
follows: struct timer_struct timer_name. 
Reference a structure variable as follows: 
tlmer_name.current. 


Current value of timer, not updated whlle timer Is 
running. Values are In microseconds rounded to 
tlok-unit on FEB Setup screen. 


Value of last sample: displayed on the tabular 
statistics screen. 


Maximum value of all samples; displayed on the 
tabular statistics screen. 


Minimum value of all samples: displayed on the 
tabular statistics screen. Should be initialized as 
~Oul. 


Number of samples. 

High four bytes of an elght-byte timer total. 
Low two bytes of an eight-byte tlmer total. 
Bytes 3 and 4 of an elght-byte timer total. 


Tick-count In microseconds when timer was 
started, restarted, or continued. For 
IIne-related conditlons at Layer 1, this value Is 
stored in /1_tick_count; for non-line conditlons, 
use get_wail_Uime_286_ticks routine. 


Stopped. This variable Is polled and a zero stops 
the timer from incrementing and sets the current 
value to timer_name.current (understood as 
microseconds}. 

Running. Ail 1's In this variable causes the timer 
to Increment, showing a value that equals 
(wall-time ticks - timer_name.start_Uck_value) + 
timer_name.current. 


For future use. 
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Table 65-5 
Timer Variables 


Type Variable Meaning 


extern unsigned long I1_tick_count This variable counts ticks from 
the start of Run mode. 
Tick=seo, mseo, etc., 
depending on FEB setup. 
Subtraot early value from later 
value to create a timer. 
ACTIONS: 
{ displayf (“ %id mseecs ”, 
(!7_flck_count - 
timer_name.start_tick_value));)} 
Add to start_of_run_time to 
determine more precise current 
time for time-stamping events. 
Line Setup configured for 
emulate or monitor mode. 


extern unsigned long start_of_run_date Date when Run mode entered. 

Byte 1 (low byte) Indicates day; 
byte 2 stores month; and bytes 
3 and 4 Indicates year. May be 
used to tlme-stamp events. 
See also start_of_run_time. 
Line Setup configured for 
emulate or monitor mode. 


extern unsigned long start_of_run_time Time when Run mode entered. 
Byte 1 (low byte) Indicates 
seconds; byte 2 stores minutes; 
and byte 3 Indicates hours. 
May be used to time-stamp 
events. See also 
Start_of_run_date and 
if_tick_count. t 
Line Setup configured for 
emulate or monitor mode. 


ee 


In the example below, the adisplayf (or tracef) routine uses tlmer varlables to time-stamp good BCCs on the DCE 
side, (Similar programming could determine the current date.) The tick unlt selected on the FEB Setup menu is 
seconds. Adjust the program as needed for other tick unlts. 


{ 

extern unsigned long start_of_run_date, start_of_run_time, t1_tick_count; 
unsigned short seconds, hours, minutes, tick_mins, tick_seces, tick_hours; 
#define SECS (run_time) (unsigned short) (run_time & Oxff) 

#define MINS(run_time} ({unsigned short) (run_time >> 8) & Oxff) 
} 


—- 


STATE: time 
CONDITIONS: DCE GOOD_8CC 
ACTIONS: 
{ 
fick_secs = []_tick_count % 60; 
tick_mins = (U1_tick_count + SECS(start_of_run_time)) / 60; 
tick_hours = (tick_mins + MINS (start_of_run_time}) / 60; 
displayf(“Time: %.2d:%.2d:%.2d\n", 
(unsigned short) (((start_of_run_time >> 16) & Oxff) + tick_hours)%24, 
(MINS (start_of_run_time) + tck_mins) %60, 
(SECS (start_of_run_time) + tick_secs) %60); 
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(B) 


(C) 


The other tick-counter is on the MPM and is referred to as the wall-time clock. 
This clock ticks once per millisecond and drives the timers displayed on the 
statistics results screens—at least while they are incrementing. At the moment a 
timer stops incrementing, the programmer can reach in. and replace the 
incremented value with a timer value based the FEB tick-counter instead. 


The current value of this wall-time tick-counter is available to the program via 
the get_wall_time_286_ticks routine, The current value always reflects both the 
number of ticks and the actual elapsed time (“wall time”) since the program 
entered Run mode. 


Running 


While it increments on the stats screen, a timer always is driven by wall-time 
ticks. To start a current timer incrementing, first you must have sent a stat 
message to correlate the timer structure with a timer line on the stats screen. At 
that point the simple statement timer_name.running = -O will start the timer. 
The value of the timer at any given time while it is running will be the MPM 
(wall-time) ticks minus the timer_name.start_tick_value plus any 
timer_name.current value. 


To stop a timer, change timer_name.running to zero. The current column of 
the timer will immediately display the value of timer_name.current (zero, unless 
you have done something in your program to calculate the current value of the 
timer). The stats display will interpret timer_name,current as a value in 
microseconds and convert it to the unit selected for that timer line. 


Restart 


The translator has two different versions of the timer restart action, depending 
on what condition precipitated the action. The first version is used if the 
condition was data-related (or ElA-related) and time ticks are enabled on the 
FEB Setup menu. Here is this data-timer version: 


unsigned long temp; 

convert_tick_count (I1_tick_count, &temp); 
Umer_name. current = 0; 

tlmer_name. start_lick_value = temp; 
timer_name. running = -0; 


The convert_tick_count routine converts //_tick_count into microseconds and 
stores the result in temp. The value of temp is assigned immediately to 
timer_name.start_tick_value. When the 68010 sees that timer_name.running 
equals the one’s complement of zero, it subtracts the start-tick value from the 
l1-tick count and displays the difference in the current column of the timer line. 
Since the start-tick value was derived a moment before from the li-tick count, 
the difference will be zero. The current column on the stats screen should begin 
a timer at zero following a restart. 
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A slightly different version of the program is used if the condition was 
nondata-related or if time ticks are disabled in the FEB. The 
convert_tick_count routine is not used and the following routine is used in its 
place: 


get_wall_time_286_ticks (&temp); 


This routine returns the current value of the wall-time tick-counter, in 
milliseconds zero-padded to microseconds. It stores the value in temp and the 
program proceeds as above. 


(D) Continue’ 


(E) 


(F) 


The timer-continue action is very similar to the restart. There are just two - 
differences. One, the action is enclosed in an if statement that verifies that 
timer_name.running equals zero—that the timer actually is stopped, in other 
words; and two, timer_name.current is not set to zero, but retains the value it 
received the last time the timer stopped. 


Stop 
Here is one of the two versions of a timer stop action: 


if (timer_name.running {= 0) 
{ 
unsigned long temp; 
convert_tick_count (il_tick_count, &temp); 
timer_name.current += temp - timer_name, start_tick_value; 
timer_name. running = 0; 
} 
In this translation, the start-tick value is subtracted from the current tick count, 
and any pending current value (held over if the timer was continued) is added 
in. The result is a new timer_name.current value. ‘This value is posted to the 
stats screen as soon as the 68010 sees timer_name.running = 0. 


The other version of the stop action uses get_wall_time_286_ticks instead of 
convert_tick_count. 


Sample Action 

The code that produces the sample action is identical to the code that sampled a 
counter. See Section 65.1(B). The timer_name.sample_count variable’s not 
equaling zero causes minimum, maximum, and average values to be displayed. 


65.3 Accumulators 


Shown below is the structure of an accumulator as the translator declares it (and 
as the 68010 accesses it to update the statistics screens). Also refer to 

Table 65-6. Note that there is no current value, since an accumulator neither 
counts nor times. There are no “previous” and “old” values, because in its 
spreadsheet implementation an accumulator never is tested in a Conditions 
block. 
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Struct accumulator_struct 


{ 


unsigned long tast; 
unsigned long maximum; 
unsigned long minimum; 
unsigned short sample_count; 
unsigned tong total_high: 
unsigned short total_low_low; 
unsigned short total_low_high; 
unsigned short changed; 

}; 


Struct accumulator_struct accumuiator_name={0,0,-Oul); 


Here is the translator's version of an accumulate action when the object of the 
accumulation (selected by the user) was the maximum sampled value of a 
counter named framechar. 


accumulator_name.last = accumulator_framechar. maximum; 
if (accumulator_name.tast > accumulator_name. maximum) 


{ 


accumulator_name.maximum = accumulator_name.last; | 


} 


if (accumulator_name.iast < accumulator_name.minimum) 


{ 


accumulator_name.minimum = accumulator_name.last; 


} 


accumulator_name.sample_counit+; 


{ 


unsigned long temp; 
temp = (accumulator_name.last & OxO000ffff) + accumulator_name.total_low_low; 


accumulator_name.total_low_low = temp; 
temp = (accumulator_name, last >> 16) + accumulator_name.total_low_high + {temp >> 16); 


accumulator_name,total_low_high = temp; 
accumulator_name.total_high += temp >> 16; 


} 


accumulator_name. changed = -0; 


A stat message must be sent so the CPM can correlate a line on the statistics 
results screen with the correct accumulator. The stat message is documented in 
the previous section on counters. The accumulator stat message is different only 
in respect that the staf_msg.type element should be set to 0 instead of 256. 


The accumulator_name,sample_count variable’s not equaling zero causes 
minimum, maximum, and average values to be displayed. 


65-13 


INTERVIEW 7000 Serles Advanced Programming: _ATLC-107-951-108 


Table 65-6 
Accumulator Structures 


Meaning 


Type Variable 
Structure Name; accumulator_struct 
unsigned long last 
unsigned fong maximum 
unsigned fong minimum 


unsigned short 


unsigned long 
unsigned short 


unsigned short 
unsigned short 


sample_count 
total_high 


total_low_low 


total_low_high 
changed 


Structure of an accumulator, Declared as type 
struct, Declared automatically by program when 
the user softkey-enters an ACCUMULATE 
actlon. Specific accumulator assigned to 
structure as follows: . struct accumulator_struct 
accumulator_name, Reference a structure 
varlable as follows: accumulator_name.last. 


Value of last sample; displayed on the tabular 
6tatistics screen. 


Maximum value of all aamples; displayed on the 
tabular statistics screen, 


Minimum value of all samples; displayed on the 
tabutar statistics screen. Should be Initlalized as 
~Oul. 


Number of samples. 


High four bytes of an elght-byte accumulator 
total, 


Low two bytes of an elght-byte accumulator 
total. 


Bytes 3 and 4 of an eight-byte accumulator total. 


For future use. 


65.4 Routines 
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get_68k_phys_addr 


Synopsis 


extern unsigned tong get_68k_phys_addr(variable_ptr); 


unsigned char * variable_ptr; 


D iption 


This routine converts the address of a specified variable in the 80286 processors 
(MPM boards) to 68010 (CPM) format. This routine must be declared. 


Inputs 


The only parameter is the address to be converted. 
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Returns 


The get_68k_phys_addr routine returns the converted address. 


Example 


See send_stat_message routine. 


send_stat_message 
Synopsis 
extern void send_stat_message(struct_stat_msg_ptr); 


Struct stat_msg 


{ 

unsigned short op_type; 
unsigned shori type; 

unsigned long object_name; 
unsigned long object_address; 


): 


struct stat_msg * struct_stat_msg_pir; 

Description 

The send_stat_message routine sends the stat message structure to the 68010 
CPU (CPM board). The current use of this routine sends the addresses of 
program counters, timers, and accumulators in the 80286 processors (MPM 


boards) to the CPM board where the tabular and graphic statistics displays are 
located. 


The routine is called only one time in a program for each named counter, timer, 
or accumulator. Entering COUNTER as a condition or action (or TIMER or 
ACCUMUL as actions) via softkey on the Protocol Spreadsheet automatically 
declares the counter named and sends the stat message. 


Inputs 


The only parameter is a pointer to the structure of the stat message. For an 
explanation of the elements of the stat message, see Table 65-3. 


Example 
You plan on incrementing a counter named “dte_info” when a DTE Info frame 
is detected. 


{ 

Struct 

{ 
unsigned short op_type; 
unsigned short type; 
unsigned long object_name; 
unsigned long object_address; 
} stat_msg; 
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struct counter_structure 
{ 
unsigned long current; 
unsigned tong last; 
unsigned long maximum; 
unsigned tong minimum; 
unsigned short sample_count; 
unsigned long totai_high; 
unsigned short total_low_low; 
unsigned short total_low_high; 
unsigned short out_of_range; 
unsigned short changed; 
unsigned long prev; 
unsigned long old; 
}; 
struct counter_structure counter_dte_info = {0, 0, 0, -Oul}; 
extern unsigned long get_68k_phys_addr(); 
} 
LAYER: 2 
STATE:send_stat_message 
CONDITIONS: ENTER_STATE 
ACTIONS: ‘ 
{ 
Stat_msg.op_type = 2560; 
Stat_msg. type = 256; ; 
stat_msg. object_name = get_68k_phys_addr(“dte_info"); 
Stat_msg.object_address = get_68k_phys_addr(&counter_dte_info); 
send_stat_message(&stat_msg); 
} 
NEXT_STATE: count_info 
STATE: count_Info 
CONDITIONS: DTE INFO 
ACTIONS: 
{ 
counter_die_info. current++; 


) 


get_wall_time_ticks 


Synopsis 


extern void get_wall_time_ticks(ticks_68k_format_ptr); 
unsigned tong ° ticks_68k_format_ptr; 


Description 

The get_wall_time_ticks routine gets the number of wall-time ticks (in CPM 
storage format) from the time (#) was hit. The wall clock gives millisecond 
resolution rounded to microseconds. 


Inputs 
The only input is a pointer to the location where the returned time-tick value 
will be stored. 
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Example 


{ 


unsigned long ticks; 
} 
LAYER: 2 
STATE: get_ticks 
CONDITIONS: KEYBOARD *“ * 
ACTIONS: 


{ 


get_wall_time_ticks(&ticks) ; 
} 


get_wall_time_286_ticks 
Synopsis 


extern void get_wall_time_286_ticks(ticks_286_format_ptr); 
unsigned long * ticks_286_format_ptr; 


Descripti 


The get_wail_time_286_ticks routine gets the number of wall-time ticks (in 
MPM storage format) from the time {m=} was hit. The wall clock gives millisecond 
readings rounded to microseconds. Use this routine prior to setting the 
start_tick_value in a timer action when Time Ticks: % has been selected on 
the Front-End Buffer Setup screen. Also use this routine to derive the 
start_tick_value if the condition is not line-related, e.g., KEYBOARD, even when 
time ticks are enabled on the FEB Setup menu. 


Inputs 


The only input is a pointer to the location where the returned time-tick value 
will be stored. 


Exa mple 


{ 
unsigned long ticks_286; 


) 


LAYER: 3 
STATE: get_ticks 
CONDITIONS: KEYBOARD * ” 
ACTIONS: 
{ 
get_wall_time_286_ticks(&ticks_286); 
displayf ("“%lu", ticks_286); 
} 
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convert_tick_count 
Synopsis 
extern vold convert_tick_count(mpm_format_ticks, converted_ticks_ptr); 


unsigned long mpm_format_ticks; 
unsigned long * converted_ticks_ptr; 


Description 


The convert_tick_caunt routine converts a. designated tick count into 
microseconds. 


Use this routine to derive the start_tick_value for a timer action if ticks are 
enabled on the FEB Setup menu and the condition is line-related, e.g., RCV 
INFO. 


Inputs 


The first parameter is a designated tick count as long as it is in MPM storage 
format. It may be any of the layer tick counts. The unit of the //_tick_count 
(and other layers’ tick counts) value is determined on the Front End Buffer 
menu. 


The second parameter is a pointer to the location where the returned tick count 
converted to microseconds will be stored. 


Example 


{ 
extern unsigned long ll_tick_count; 
unsigned long converted_lticks; 
} 
LAYER: 1 
STATE: convert_ticks 
CONDITIONS: RECEIVE GOOD_BCC 
ACTIONS: 
{ 
convert_tick_count(il_tick_count, &converted_ticks); 
dispiayf (“%lu”, converted_ticks); 


) 
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Figure 66-1 Primitive Data Unit and sample Pointer-List Buffer being passed down 


the layers. 


66-2 


JUL ‘90 


66 OS! 


66 OSI 


The most convenient tools for handling protocol! headers while data is moving down and up 
the layers in the INTERVIEW are the spreadsheet SEND and GIVE_DATA actions in the various 
protocol packages. For instances when a protocol package is not loaded, such as when you 
are developing a new protocol or simply using a protocol that is not yet an option on the 
Layer Setup screen, OSI structures, variables, and routines in C become essential tools also. 


66.1 Structures 


The programmer may access the information in primitive data units conveniently by 
using a C structure as a multibyte pointer that is superimposed on data in the PDU’s. 
Before using a structure-pointer, it is necessary to understand the contents of IL 
buffers and primitive data units. All structures referenced may be found in 

Table 66-1. 


(A) Interlayer Message Buffers 


1. Configuring the number/size of IL buffers. By default, there are a maximum 
sixteen IL buffers in use at a given time. Each buffer's size is 4,096 bytes. 
You may change the number and size of the interlayer (IL) buffers. The IL 
BUFS softkey on the Protocol Spreadsheet presents seven number/size 
combinations that allocate 64 Kbytes of RAM to IL buffers. See Section 27. 
In addition to these softkey selections, there are two C preprocessor 
directives the programmer may use to reconfigure the number and/or size of 
IL buffers: 


(a) #pragma il_buffers sets the number of IL buffers that will be available 
at a given time. Following the directive, enter a space and then a 
decimal integer within the range 4 through 255. In the following 
example, the number of buffers is set to 25: 


#pragma il_buffers 25 


The specified number of buffers wilt override the number selection on 
the Interlayer Buffers menu. The buffer size indicated on the Interlayer 
Buffers menu will remain unchanged, however, unless altered via the 
#pragma il_buffer_size directive. 
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(b) #pragmna il_buffer_size sets the size of IL buffers. Following the 
directive, enter a space and then a decimal integer within the range 33 
through 65535. These values include the 32-byte buffer header. (See 
Section 2. below.) In the following example, the size of buffers is set 
to 8 Kbytes: 


#pragma il_buffer_size 8192 


The specified buffer size will override the size selection on the 
Interlayer Buffers menu. The number of buffers indicated on the 
Interlayer Buffers menu will remain unchanged, however, unless altered 
via the #pragma il_buffers directive. 


Be careful when you are passing messages down from higher layers that 
you do not make the buffer size too small. Even small messages require 
a buffer large enough to accommodate the overhead of linked lists. 


These two directives provide the programmer with more flexibility in 
configuring IL buffers than the Protocol Spreadsheet softkeys. With the 
#pragmas, the available RAM for IL buffers may exceed the 64-Kbyte 
threshold of the IL BUFS selections. 


The memory required for IL buffers is the product of the number and size 
of the buffers (number °* size). If this amount exceeds available memory, 
your program will not compile and the message “Error 219: Out of memory 
during compilation — program too big” will be displayed. Available memory 
for IL buffers varies depending on the complexity of your program. 


IL buffer components. IL buffers may be one of two kinds: data-character 
or pointer-list. In buffers being passed up the layers, data-character buffers 
(Figure 66-2) are always used. In buffers going down the layers, pointer-list 
buffers (Figure 66-1) are primarily used. The difference is that pointer-tist 
buffers contain list-nodes which provide information about the location of 
data (or “lists”) inserted or referenced in the buffer, while data-character 
buffers do not. 


(a) Header. Each IL buffer contains a header that stores useful information 
such as the status of the maintain bits that prevent the buffer from being 
returned to the general pool; the position of the buffered data in the 
INTERVIEW’s display buffer; and the tick count (time) when the data 
was buffered from the line. (See il_buffer structure.) 


(b) Service Data Unit. The IL buffer also contains the data itself. This data 
component, the service data unit (or “SDU”), is added to as the buffer is 
passed down the layers, and subtracted from as a buffer travels up the 
layers. A data-character IL buffer includes all the data that was present 
when the data was first buffered, and the contents of this buffer do not 
change as the buffer is passed up the layers. What changes is the service 
data unit, derived from the data-start offset in the PDU. 
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The first part of the SDU in a pointer-list buffer is a list-header node 
(structure i/_list_header) which contains information about the location 
of the first and last text nodes. As a buffer is passed down from Layer 
3 to Layer 2 in X.25 (see Figure 66-1), a new text node containing a 
Layer 3 protocol header is inserted in buffer. Since the Layer 3 data 
will precede user data, the list node for the protocol information is 
referenced ahead of any other list nodes, changing the first-node 
reference in the list header. (If text is appended to the end of existing 
data, the list node referenced as last will change.) 


The SDU in a pointer-list buffer also includes Hist nodes (structure 
il_list_node) which give a pointer to data, the length of the data pointed 
to, and the offset from the start of the buffer to the next list node. 


Finally, the service data unit in ail buffers includes data, whether copied 
into the buffer (usually protocol information) or located in memory 
outside of the buffer (usually user data). 


__ Data-Character 
~~ IL_BUFFER data_start_offset: 
\ 


“—4-«—- at Layer 2 
at Layer 3 


ent 
l 


Layer2 % spu Size 
# Layer 3 


Figure 66-2 Primitive Data Unlt and sample Data-Character Bulfer being passed up 
the layers. 
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(B) Primitive Data Units 


Like interlayer message buffers, PDU’s have a format that is dependent on 
which direction the primitive is being passed. Refer again to Figure 66-1 and 
Figure 66-2. 


1, 


IL buffer number. The buffer number to be passed with the primitive is 
always stored in the primitive. This buffer number is actually an 
80286-processor segment number. 


Data-start offset. The offset from the beginning of the buffer to the 
beginning of the service data unit for a given layer is different for the two 
types of buffers. In a pointer-list buffer going down the layers, the 
data-start offset will indicate the offset from the beginning of the buffer to 
the list-header node. This offset will vary if different linked lists have been 
started at different layers. Each list will have its own list header. In a 
data-character buffer going up the layers, the data-start offset will change 
from layer to layer. For example, a buffer containing X.25 data that is 
being passed from Layer 2 to Layer 3 will have an offset at Layer 3 two 
bytes beyond the offset at Layer 2. 


Data length. The size of the SDU in a data-character buffer also varies 
from layer to layer. In the example just given, the SDU will be smaller by 
two bytes at Layer 3 than it was at Layer 2. In pointer-list buffers, the 
length of ail data is unknown at any given layer. 


(C) Accessing Information in Structures 


There are two stages that are preliminary to accessing the information in these 
structures. The first step is to convert the 80286-processor segment number into 
a 32~bit address. The second stage is to place a pointer, in the shape of an IL 
buffer structure, at that address. Let’s use an IL buffer as an example. 


1. 


Converting a segment number. The IL-buffer segment number is returned 
any time you access one of the external, protocol-independent j/_buffer 
variables listed in Table 66-1. These variables have names like 
m_lo_dl_il_buff and up_n_il_ buff. 


To make a pointer to an IL buffer, (1) shift the 80286 segment number to 
the left sixteen bits, since a full address in the 80286 is 32 bits long; (2) cast 
it as a /ong, so that the segment number is in the high 16 bits and the offset 
to a buffer for that segment is zero (the low 16 bits); and (3) cast it as a 
pointer. The following expression will take care of all three requirements: 


(void *) ((long) m_lo_dt_ll_buff <<16); 


Now you have a pointer to the first memory location of the most recent 
monitor-mode IL buffer passed up from Layer 2 to Layer 3. An 
upward-moving IL buffer was illustrated in Figure 66-2. The precise 
structure of both the IL buffer is given in the following declaration. 
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{ 


Struct il_buffer 
{ ‘ 

unsigned short tock; 

unsigned short maintain_bits; 

unsigned short buffer_size; 

unsigned short transmit_tag; 

unsigned short receive_tag; 

unsigned long char_buff_frame_start; 

unsigned long char_buff_frame_end; 

unsigned short tick_count_high; 

unsigned short tick_count_mid; 

unsigned short tick_count_low; 

unsigned short avaiiable_space_offset; 

unsigned short bytes_remaining; 

unsigned tong bec_indicator; 

unsigned char data {4064}; 

} 


2. Create a siructure-pointer at a given address. First, declare the structure of 
ll_buffer, as indicated above. Then declare i/_buffer_pointer as a 
structure-pointer, as follows: 


struct il_buffer * Il_buffer_pointer; 


Converting the segment number and assigning it to il_buffer_pointer may be 
accomplished with this one statement: 


it_buffer_pointer = (void *) ((long} m_lo_dt_il_buff <<16); 


Now a structure has been created around the most recent upward—moving IL 
buffer at Layer 3. This means that rather than moving a pointer around in 
the IL buffer, you can access elements in the buffer directly. The 
tick_count_low variable, for example, would be called 
il_buffer_pointer->tick_count_low. (The -> operator is used in place of the 
dot operator in structure-pointers.) . 


The first element of the data string would be called 
il_buffer_pointer->data{0]. Here is a program that displays on the prompt 
line the fifth data element, the packet-type byte, in every IL buffer that is 
monitored at Layer 3. 
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{ 
extern event m_lo_dl_prmtv; 
extern volatile unsigned short m_to_dl_it_buff; 
struct il_buffer 


unsigned short lock; 
unsigned short maintain_bits; 
unsigned short buffer_size; 
unsigned short transmit_tag; 
unsigned short receive_tag; 
unsigned long char_buff_frame_start; 
unsigned long char_buff_frame_end; 
unsigned short tick_count_high; 
unsigned short tick_count_mid; 
unsigned short tick_count_low; 
unsigned short available_space_offset; 
unsigned short bytes_remaining; 
unsigned long bcce_indicator; 
unsigned char data {4064}; 
}; 
struct il_buffer * il_buffer_pointer; 


LAYER: 3 
STATE: monitor_tt_ buffers 
CONDITIONS: 
{ 
m_lo_dl_prmiy 
} 
ACTIONS: 
{ 


il_buffer_pointer = (void *) ((long) m_lo_di_il_buff <<16); 
pos_cursor (0,0); 
displayf (“%02x ”, il_buffer_pointer->data{4]}); 


If you run this program, be sure to load in the Layer 2 and Layer 3 
personality packages for X.25. These packages will take care of delivery of 
the monitor primitives to Layer 3. __ 
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Type 


Variable 


Value (hex/decimal) 


Meaning 


unsigned char 


unsigned char 


unsigned long 
unsigned short 


unsigned short 


unsigned char 


unsigned short 


unsigned short 
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: pdu 


primitive_code 


path 


parameter 


relay_baton 


ll_buffer_number 


buffer_contents 


data_start_offset 


data_length 


Structure of an OSI primitive data unit (PDU), 
Declared as type struct. Use this structure as follows. 
Declare the entire structure. Make a pointer to a PDU 
by shifting m_lo_d/_pdu_seg (or up_n_pdu_seg) 16 bits 
to.the laft. Then convert this polnter to a pointer to a 
POU structure: struct pdu * pdu_polnter 

pdu_polnter =( vold *)({long)m_lo_di_pdu_seg << 16). 
Reference a structure-polnter varlable as follows: 
pdu_polnter->primitive_code, 


Codes for OSI variables are fisted in Table 66-2 
through Table 66-8. For Layer 3 primitive codes, 
for example, refer to Table 66-4. The value of this 
varlable Is atso stored In external variable 
m_lo_di_prmtv_code (or up_n_prmtv_code). 


Path number, both directions. The value of this 
varlable Is also stored In external variable 
m_o_al_prmtv_path (or up_n_prmtv_path). 


For future use. At present, under user control. 


Malntaln bit passed with an Interlayer-message 
buffer, both directions. Zero In this variable 
Identifles maintaln bit. 


Segment number of the Interlayer-message 
buffer, both directions. The value of this varlable 
is atso stored In external variable m_lo_ai_ll_buff 
(or up_n_Il_buff). 


Contalns data-character buffer type. Must be 
used for buffer being passed up. 


Contains pointer-list buffer type. May be used 
for buffers being passed up, but Is currently used 
primarlly for buffers belng passed down. 


Offset from the beginning of the buffer to tha 
header node In the SDU of an interlayer-message 
buffer In an OS! primitive being sent down from a 
layer above. in a primitlve being sent up froma 
jayer below, It is the offset to the SDU. Varles 
according to the layer at which the buffer is 
located. For example, In a buffer passed up to 
Layer 3 from Layer 2, the offset would be to the 
beglnning of the Layer 3 header, bypassing Layer 
2 header Information. The value of this varlable 
ls also stored In external variable 
m_lo_di_sdu_offset {or up_n_sdu). 


Length of the service data unlt, including headers 
and user data. Only for primitives sent up from 
layer below, Varles with the layer where the 
buffer is located. For example, at Layer 3, 
tength would exclude Layer 2 header (or trailer) 
informatlon. The value of this varlabte Is also 
stored In externat varlable m_lo_a/_sdu_size, 
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Table 66-1 (continued) 


Type 


Variable 


Value (hex/decimal) 


Meaning 


Structure Name: il_buffer 


unsigned short 


unsigned short 


unsigned short 


unsigned short 


unsigned short 


unsigned long 


unsigned long 
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lock 


malntain_bits 


buffer_size 


transmit_tag 


recelve_tag 


char_buff_frame_start 


char_buff_frame_end 


1000/4096 
21-HH133-65535 


hon 


hon=so 


_Struoture of an Interlayer-message buffer, both 


directions. Declared as type struct. Use this 
structure as follows. Declare the entire structure. 
Make a pointer to an il_buffer by shifting 
m_lo_di_il_buff (or up_n_ll_butf) 16 bits to the left: 
il_buffer_pointer = (vold *) ( (long) (to_dl_ll_buff << 16). 
Then convert this pointer to a pointer to an li_buffer 
structure: struct ll_buffer * Il_buffer_polnter. 
Reference a structure-polnter varlable as follows: 
l_buffer_polnter->tIck_count_low. 


internal variable which prevents structure from 
belng updated by more than one program at the 
same time. 


Two-byte variable which provides the status of 
the malntaln bits. A bit with a value of 1 is In 
use. 


default vaiue 
Specific value depends on buffer size set via 
tL_BUFFERS programming block or #pragma 
Il_buffer_size 


Bits 1-3 define bee Indication: 


no bce 

good bcc 

bad bee 

abort 

half bad bee (DDCMP} 


Bits 4-8 for future use. 
Bits 1-3 define bee indication: 


no bee 

good bcc 

bad bee 

abort 

half bad bec (DDCMP) 


—mess f 


frame fits in buffer 
frame too large for the buffer 
Bits 6-8 for future use. 


Location In the character buffer of the start of 
the buffered data. 

Location Jn the character buffer of the end of the 
buffered data. 


(ii_bulfer structure continued on next page) 
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Table 66-1 (continued) 


Type Variable 


Value (hex/decimal) 


Meaning 


il_buffer (continued) 


unsigned short tick_count_high 


unsigned short tick_count_mid 
unslgned short tlck_count_low 
unsigned short avallable_space_offset 
unsigned short bytes_remaining 
unsigned long bec_Indicator 
unsigned char data [4064] 


Structure Name: il_list_header 


unsigned short first_node_offset 
unsigned short last_node_offset 
unsigned long reserved 
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Value of Internal varlable that counts the number 
of tlmes /i_tick_count has reached Its maximum 
value. Together, the three /i_buffer tick-count 
varlables preserve at each layer the original time 
when the end of the data (BCC) was clocked Into 


the buffer. 


16 high-order bits of 32-bit /7_tick_count. 
16 low-order bits of 32-bit /7_tick_count. 


Offset to the next avallable space In the 
Interlayer-message buffer. 


Available number of bytes remaining in the buffer. 
reserved 


Contains all data Including each layer's header 
Information, as well as the first of two block 
check characters. Does not vary from layer to 
layer. Default size Is 4064, but may range from 
33-65535 (hex 21-ffff) depending on the buffer 
size set via IL_ BUFFERS programming block or 
#pragma ll_buffer_size. 


Structure of the header node In an 
Interlayer-message buffer. Only for primitives 
sent down from the layer above. Declared as 
type struct. Use this structure as follows. 
Declare the entire structure. Make a pointer to 
an Il_llst_header by shifting up_n_Il_buff (or 
m_lo_di_ll_buff } 16 bits to the left and adding the 
data_start_offset from the PDU structure (also 
stored as external vartable up_n_sdu or 
m_lo_di_sdu_offset): 

i_list_header_pointer = 

(vold *)(((tong)up_n_lIl_buff) << 16) + up_n_sdu). 
Then convert this pointer Into a polnter to an 
I_llst_header structure: 

struct It_list_header * Il_list_header_pointer. 
Reference a structure-polnter varlable as follows: 
IL\ist_header_pointer->last_node_offset. 


Offset from the beginning of the buffer to the 
first text node in the buffer. Varies according to 
the iayer at which the buffer is located. At Layer 
2, the offset would be to different starting node 
than at Layer 3. 


Offset to the location of the Jast text node In the 
buffer, from the beginning of the buffer. 


reserved 
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Table 66-1 (continued) 


Type Variable Value (hex/decimai) Meaning 
Structure Name: Il_list_node Structure of text nodes In an Interlayer-message 


buffer. Only for primitives sent down from the 
layer above. Declared as type struct, Use this 
structure as follows, Declare the entire 
structure. Make a pointer to an il_list_node by 
shifting up_n_il_buff (or m_lo_di_Il_buff) 16 bits to 
the left and adding the first_node_offset (or 
last_node_offset) from the il_list_header 
structure: {t_list_node_pointer = 

(vold *)({((long)up_n_il_ buff << 16) + 
I_list_header_pointer->first_node_offset). Point 
to the next node as follows: 

next_node_pointer = {il_llst_node_polnter + 
i_llst_node_pointer->next_node_offset). 


unsigned char * data_pointer Pointer to the data In a text node, 
unsigned short data_length Length of the data In a text node. 
unsigned short next_node_offeet Offset to the location of the next text node in the 


buffer, from the beginning of the buffer. 


Generally, there Is a text node for each layer'e 
header Information and one for the user data. A 
buffer that started at Layer 3 would have two 
text nodes, one for Layer 3 header information 
and one for user data (If any). At Layer 2, the 
buffer would acquire an additlonal text node. 
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66.2 Variables 


OSI variables are layer-specific. The information stored in the OSI variables may be 
obtained by using the structure-pointer to IL buffers and primitives. But rather than 
requiring the user to repeat this process at each layer as a buffer moves through the 
layers, monitor and emulate variables have been made-available at Layers 2-7 to 
store layer-specific, as well as general, information: the interlayer-buffer number, 
the offset to the service data unit, the path number, the size of the SDU, the 
Segment number of the PDU, etc. There are also event variables which indicate that 
a primitive has.been received.at a. given layer. Table 66-2 through Table 66-8 give 
the current OSI variables and their meanings. 


The exchange of connect primitives shown primarily in Figure 33-4 is demonstrated in 
Figure 66-3 using C variables and routines. The SEND actions insert data in a buffer 
and send the buffer in a DATA REQ primitive. See Section 66.3 for an explanation of 
the _insert_il_buff_list_cnt and send primitive routines. The conditions use event 
variables to detect primitives and non-event variables to identify specific primitive 


types. 


LAYER 3: 


{send _dl prmtv_below 


(l_buffer_nurfber, rélay_baton, {io_di_ prmtv && 


data atert atleast © (1o_dl_prmtV¥_code == 0x43)} § SEND RESTART 


0x40, path};} 


Freres: | 
ea! pL_oaTaA LL, 
~ REQ ? 
NC 7 
uw 


DL_CONNECT 
DL_CONNECT CONF 
REQ 


LAYER 2: etc. 


{send di prmtv_above 


{up_di_prmtv && (lL_buffer_rumber, rélay_baton, 


(up_di_prmtv¥_code == 0x40}} / SEND SABM ~ data “start_offset, size, 


x43, path) ;} 


PH_DATA 


nea NO 


Figure 66-3 Layer 3 uses connect primitives to be sure that the Layer 2 entity below has 
established a link. 
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Table 66-2 
Layer 1 OS) Variables 


Type Variable Value (hex/decimai) Meaning 

extern volatile unsigned char ph_prmtv_type 20/32 ph activate req 
21/33 Ph activate Ind 
22/34 ph activate resp 
23/35 ph activate conf 
24/36 ph data req 
25/37 ph data Ind 
2a/42 ph reset req 
2b/43 ph reset Ind 
20/44 ph reset resp 
2d/45 ph reset conf 
20/46 ph deactivate req 
2f/47 ph deactivate ind 
30/48 ph debug req 
31/49 ph debug Ind 
33/51 ph error report Ind 
34/52 ph xmit req 
35/53 ph set idle req 
38/56 ph mgt faclilty req 
39/57 ph mgt facliity Ind 
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OS] primitive code for primitives 
moving between Layers 1 and 2. 
Line Setup configured for 
emulate mode only. 


JUL '90 


66 OSI 


Table 66-3 
Layer 2 OSI Variables 


Type Variable Value (hex/decimal) Meaning 


extern event lo_ph_prmtyv True when an OSI primitive is 
recelved at Layer 2 from Layer 
1. Line Setup configured for 
emulate mode only. 


extern event m_lo_ph_prmtv True when an OS! primitive Is 
received at Layer 2 from Layer 
1. Line Setup configured for 
emulate or monitor mode. 


extern event up_dli_prmtyv True when an OSI primitive Is 
recelved at Layer 2 from Layer 
3. Line Setup configured for 
emulate mode only. 


extern volatite unsigned short lo_ph_pdu_seeg OSI primitive data unlit (PDU) 
IAPX-286 segment number 
recelyed at Layer 2 from Layer 
1. This segment number can 
be converted to a polnter by 
shifting It teft 16 bits. Line 
Setup configured for emulate 
mode only. 


extern volatile unsigned short m_lo_ph_pdu_seg OSI primitlve data unit (PDU) 
IAPX-286 segment number 
recelved at Layer 2 from Layer 
1. This segment number oan 
be converted to a polnter by 
shifting It left 16 blts. Line 
Setup configured for erutate or 
monitor mode. 


extern volatile const unsigned char lo_ph_prmtv_code 21/33 ph activate ind 
23/35 ph activate conf 
25/37 ph data Ind 
2b/43 ph reset Ind 
20/45 ph reset conf 
2/47 ph deactivate ind 
31/49 ph debug ind 
33/51 ph error report ind 
39/57 ph mot facllity Ind 


OSI primitive code recelved at 
Layer 2 In a PDU from Layer 1. 
Line Setup configured for 
emulate mode only. 


extern volatile const unsigned char m_lo_ph_prmtv_code 24/36 td ph data Ind 
25/37 rd ph data Ind 
OSI primitive code recelved at 
Layer 2 In a PDU from Layer 1. 
Line Setup configured for 
emutate or monitor mode. 
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Table 66-3 (continued) 


Type 


Variable Value (hex/decimal) 


Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatiia unsigned short 


extern volatile unsigned short 
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lo_ph_prmtv_path 0-8 


m_lo_ph_prmtv_path 0-8 


lo_ph_ll_buff 


m_lo_ph_ll_buff 


to_ph_sdu 


m_lo_ph_sdu_offset 


m_lo_ph_sdu_size 


up_di_pdu_seg 


Path number recelved at Layer 
2 In a PDU from Layer 1. Line 
Setup configured for emulate 
mode only. 


Path number recelved at Layer 

2 in a PDU from Layer 1. Line 

Setup configured for emulate or 
monitor mode. 


Interlayer~buffer number (an 
IAPX-286 segment number) 
received at Layer 2 Ina POU 
from Layer 1. This segment 
number can be converted to a 
pointer by shifting it left 16 bits. 
Line Setup configured for 
emulate mode only. 


Interlayer-buffer number {an 
JAPX-286 segment number) 
recelved at Layer 2 In a PDU 
from Layer 1. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode, 


In OSI primitive recelved at 
Layer 2 from Layer 1, the offset 
to where the service data unit 
begins, Line Setup configured 
for emulate mode only. 


In OSt primitive received at 
Layer 2 from Layer 1, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 


Size of the service data unit In 
an intertlayer-message buffer, 
displayed as SIZE on the Layer 
2 trace screen. Recelved at 
Layer 2 from Layer 1. Same as 
data_length Ina PDU. Line 
Setup configured for emulate or 
monitor mode. 


OS! primitive data unlit (PDU) 
iAPX-286 segment number 
recelved at Layer 2 from Layer 
3. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 
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Table 66-3 (continued) 


Type 


Variable 


Value (hex/decimal) Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern unsigned tong 


up_di_prmtv_code 


up_di_prmtv_path 


up_di Il_butf 
up_di_sdu 
12_tIlck_count 


40/64 
42/66 
44/68 
48/72 
4a/74 
4c/76 
40/78 


60/80. 


52/82 
56/88 


0-8 


d!J conn req 

dl conn resp 

di data req 

dl expd data req 
di reset req 

dl reset resp 

di disconn req 


. dl debug req 


di unit data req 
di mgt facllity req 


OSI primitve code recelved at 
Layer 2 in a PDU from Layer 3. 
Line Setup configured for 
emulate mode only. 


Path number recelved at Layer 
2 In a PDU from Layer 3. Line 
Setup configured for emulate 
mode only. 


Intertayer-buffer number (an 
IAPX-286 segment number) 
recelyed at Layer 2 In a POU 
from Layer 3. This segment 
number can be converted to a 
pointer by shifting It feft 16 bits. 
Line Setup configured for 
emulate mode only. 


Offset to the start (header 
node) of the service data unlit in 
an interlayer-message buffer. 
Recelved at Layer 2 from Layer 
3. Same as data_start_offset In 
a PDU. Line Setup configured 
for emulate mode only. 


32-bit /7_tick_count stored In 
header of most recent IL buffer 
passed up to Layer 2. 
Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
into the buffer. Line Setup 
configured for emulate or 
monitor mede. 
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Table 66-4 
Layer 3 OSI Varlables 


Type Variable Value (hex/decimal) Meaning 


extern event lo_dl_prmtv True when an OSI primitive ie 
recelved at Layer 3 from Layer 
2. Line Setup configured for 
emulate mode only. 


extern event m_lo. dl. prmtv- True when an OS! primitive is 
received at Layer 3 from Layer 
2. Line Setup configured for 
emulate or monitor mode. 


extern event up_n_prmtv True when an OS} primitive is 
recelved at Layer 3 from Layer 
4, Llne Setup configured for 
emulate mode only. 


extern volatile unsigned short lo_di_pdu_seg OS! primitive data unit (PDU} 
IAPX-286 segment number 
recelved at Layer 3 from Layer 
2. This segment number can 
be converted to a pointer by 
shifting it left 16 bits. Line 
Setup configured for emulate 
mode only. 


extern vofatile-unsigned short m_lo_dt_pdu_seg OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 3 from Layer 
2. This segment number can 
be converted to a polnter by 
shifting It feft 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


extern volatile const unsigned char lo_di_prmtv_code 41/65 dt conn Ind 
43/67 dl conn conf 
45/69 di data ind 
49/73 d! expd data Ind 
4b/75 di reset Ind 
4d/77 di reset conf 
4t/79 d! disconn Ind 
51/81 dl debug Ind 
§3/83 di unit data Ind 
§5/85 dl error report Ind 
59/89 di mgt facility Ind 


OS! primitive code recelved at 
Layer 3 In a PDU from Layer 2, 
Line Setup configured for 
emulate mode only. 


66-18 JUL '90 


66 OS! 


Table 66-4 (continued) 


Type 


Variable 


Value (hex/decimal) 


Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 
extern volatile const unsigned char 


extern volatile Unsigned short 


extern volatile unsigned short 


extern Volatile unsigned short 


extern Volatile unsigned short 


extern volatile unsigned short 
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m_to_dt_prmtv_code 44/66 
45/69 
48/72 
49/73 
54/84 
55/85 


lo_dl_prmtv_path 0-8 
m_lo_dil_prmtv_path 0-8 


to_dl_il_buff 


m_to_dl_il_buff 


fo_di_sdu 


m_lo_dl_sdu_offset 


m_lo_dt_sdu_size 


td dl data Ind 

rd di data Ind 

td di expd data ind 
rd di expd data ind 
td di unit data Ind 
rd di unit data Ind 


OSI primitive code recelved at 
Layer 3 In a PDU from Layer 2. 
Line Setup configured for 
emulate or monitor mode. 


Path number recelved at Layer 
3 in a POU from Layer 2. Line 
Setup configured for emulate 
mode only. 


Path number recelved at Layer 
3 in a PDU from Layer 2. Line 
Setup configured for emulate or 
monitor mode. 


Interlayer-buffer number (an 
iAPX-286 segment number) 
recelved at Layer 3 in a POU 
from Layer 2. This segment 
number can be converted to a 
polnter by shifting it loft 16 bits. 
Line Setup configured for 
emulate mode only. 


interlayer-buffer number (an 
IAPX-286 segment number) 
recelved at Layer 3 In a PDU 
from Layer 2. This segment 
number can be converted to a 
pointer by shifting it left 16 bits. 
Line Setup contigured for 
emulate or moniter mode. 


In OSI primitive received at 
Layer 3 from Layer 2, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 


in OSI primitlve received at 
Layer 3 from Layer 2, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 


Size of the service data unit in 
an interlayer-message buffer, 
displayed as SIZE on the Layer 
3 trace screen. Received at 
Layer 3 from Layer 2. Same as 
data_length In a PDU. Line 
Setup configured for emulate or 
monitor mode. 
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Table 66-4 (continued) 


Type Variable Value (hex/decimal) Meaning 
LD BE a Ef ER ET 
extern volatile unsigned short up_n_pdu_seg OS! primitive data unit (PDU) 


IAPX-286 segment number 
recelved at Layer 3 from Layer 
4. This segment number can 
be converted to a pointer by 
shifting it left 16 bits. Line 
Setup configured for emulate 


mods only. 
extern volatile const unsigned char up_n_prmtv_code 60/96 h conn req 
62/98 n oonn resp 
64/100 n data req 
66/102 n data ack req 
68/104 n expd data req 
6a/106 n reset req 
6¢/108 n reset resp 
6e/110 n disconn req 
70/112 n debug req 
72/114 n unit data req 
74/116 n qual data req 
76/118 n qual data ack req 
78/120 n mot faciillty req 


OS! primitive code recelved at 
Layer 3 In a PDU from Layer 4. 
Line Setup configured for 
emulate mode only. 


extern volatile const unsigned char up_n_prmtv_path 0-8 Path number recelved at Layer 
3 in a PDU from Layer 4. Line 
Setup configured for emulate 
mode only. 


extern volatile unsigned short up_n_il_buff interlayer-buffer number (an 
IAPX-286 segment number} 
received at Layer 3 in a PDU 
from Layer 4. This segment 
number can be converted to a 
pointer by shifting it left 16 bits. 
Line Setup configured for 
emulate mode only. 


extern volatile unsigned short up_n_sdu Offset to the start (header 
node) of the service data unit In 
an Interlayer-message buffer. 
Recelved at Layer 3 from Layer 
4. Same as data_start_offset In 
a PDU. Line Setup configured 
for emulate mode only. 


extern unsigned long 13_tick_count 32-bit /f_tick_count stored in 
header of most recent IL buffer 
passed up to Layer 3. 
Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 
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Table 66-5 
Layer 4 OSI Varlables 


Type Variable Value (hex/decimal) Meaning 


extern event lo_n_prmtv True when an OSI primitive Is 
recelved at Layer 4 from Layer 
3. Line Setup configured for 
emulate mode only. 


extern event m_fo_n_prmtv- True when an OSI primitive Is 
recelved at Layer 4 from Layer 
3. Line Setup configured for 
emulate or monitor mode. 


extern event up_t_prmtv True when an OSI primitive is 
recelved at Layer 4 from Layer 
§. Line Setup configured for 
emutate mode only. 


extern volatile unsigned short lo_n_pdu_seg OSI primitive data unit (PDU) 
{APX-286 segment number 
recelved at Layer 4 from Layer 
3. This segment number can 
be converted to a pointer by 
shifting It left 16 bite. Line 
Setup configured for emulate 
mode only. 


extern volatile unsigned short m_lo_n_pdu_seg OS! primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 4 from Layer 
3. This segment numper can 
be converted to a pointer by 
shifting it left 16 bits. Line 
Setup configured for emulate or 
monitor mode, 


extern volatile const unsigned char fo_n_prmtv_code 61/97 n conn ind 
63/99 n conn conf 
65/101 n data Ind 
67/103 n data ack ind 
69/105 n expd data Ind 
6b/107 n reset Ind 
60/109 n reset conf 
6f/111 n disconn ind 
TUSAS n debug Ind 
73/115 n unit data Ind 
75/117 n qual data Ind 
77/119 n qual data ack ind 
79/121 n mgt facility Ind 
Zali122 n error report ind 


OSI primitive code received at 
Layer 4 In a PDU from Layer 3. 
Line Setup configured for 
emulate mode only. 
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Table 66-5 (continued) 


Type 


Variable 


Value (hex/decimal) Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatie unsigned short 
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m_lo_n_prmtv_code 


lo_n_prmtv_path 


m_lo_n_prmtv_path 


lo_n_il_buff 


m_lo_n_il_buff 


lo_n_sdu 


m_to_n_sdu_offset 


m_lo_n_sdu_slze 


64/100 
65/101 
68/102 
69/103 
74/116 
75/117 


td n data Ind 

td n data Ind 

td n expd data Ind 
rd n expd data Ind 
td n unit data Ind 
rd n unit data Ind 


OSI primitlve code received at 
Layer 4 In a PDU from Layer 3. 
Line Setup configured for 
emulate or monitor mode. 


Path number reoelved at Layer 
4 in a POU from Layer 3. Line 
Setup configured for emulate 
mode only. 


Path number recelved at Layer 

4 In a PDU from Layer 3, Line 

Setup configured for emulate or 
monitor mode. 


Interlayer-buffer number (an 
JAPX-286 segment number) 
recelved at Layer 4 in a PDU 
from Layer 3. This segment 
number can be converted to a 
polnter by shifting it eft 16 bite. 
Line Setup configured for 
emulate mode only. 


Interlayer-buffer number (an 
iAPX-~286 segment number) 
recelved at Layer 4 In a PDU 
from Layer 3. This segment 
number oan be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 


in OSI primitive received at 
Layer 4 from Layer 3, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 


In OSI primitive recelved at 
Layer 4 from Layer 3, the offset 
to where the service data unit 
begins, Line Setup configured 
for emulate or monitor mode. 


Size of the service data unit In 
an Interlayer-message buffer. 
Recelved at Layer 4 from Layer 
3. Same as data_lengthina 
PDU, Line Setup configured for 
emulate or monitor mode. 
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Table 66-5 (continued) 


Type 


Variable 


Value (hex/decimal) Meaning 


extern volatile unsigned short 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern unsigned tong 


up_t_pdu_seg 


up_t_prmtv_code 


up_t_prmtv_path 


up_t_il_buff 


up_t_sdu 


I4_tIlck_count 


80/128 
82/130 
84/132 
88/136 
80/142 
90/144 
92/146 
98/152 


OSI primitive data unit (PDU) 
|APX-286 segment number 
recelved at Layer 4 from Layer 
5. This segment number can 
be converted to a pointer by 
shifting it left 16 bits. Line 
Setup configured for emulate 
mode only. 


t conn req 

t conn resp 

t data req 

t expd data req 
t disconn req 

t debug req 

t unit data req 

t mgt facility req 


OSI primitive code received at 
Layer 4 In a POU from Layer 5. 
Line Setup configured for 
emulate mode only. 


_Path number recelved at Layer 


4 In a PDU from Layer 5. Line 
Setup configured for emulate 
mode only, 


Iinterlayer-buffer number (an 
iAPX-286 segment number) 
recelved at Layer 4 In a PDU 
from Layer 6. This segment 
number can be converted to a 
polnter by shifting It left 16 bits. 
Line Setup canflgured for 
emulate mode only. 


Offset to the start (header 
node) of the service data unit In 
an interlayer-message buffer. 
Received at Layer 4 from Layer 
5, Same as data_start_offset In 
a PDU. Line Setup configured 
for emulate mode only. 


32-bit 11_tick_count stored in 
header of most recent IL buffer 
passed up to Layer 4. 
Preserves at each layer the 
orlginal time when the end of 
the data (BCC) was clocked 
Into the buffer, Line Setup 
configured for emulate or 
monitor mode. 
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Table 66-6 
Layer 5 OS! Variables 


Type Variable Value (hex/decimal) Meaning 


extern event lo_t_prmtv True when an OSi primitive ts 
recelved at Layer 5 from Layer 
4. Line Setup configured for 
emulate mode only. 


extern event m_lo_t_prmtv True when an OSI primitive ts 
recelved at Layer 5 from Layer 
4. Line Setup configured for 
emutate or monitor mode. 


extern event up_&_prmtv True when an OSI primitive Is 
recelyed at Layer 5 from Layer 
6. Line Setup configured for 
emulate mode only. 


extern volatile unsigned short lo_t_pdu_seg OSI primitive data unit (PDU} 
IAPX-286 segment number 
recelved at Layer 5 from Layer 
4. This segment number can 
be converted to a pointer by 
shifting [t feft 16 bits. Line 
Setup configured for emulate 
mode only. 


extern volatile unsigned short m_lo_t_pdu_seg ; OSI primitive data unlt (PDU) 
IAPX-286 segment number 
recelved at Layer 5 from Layer 
4. This segment number can 
be converted to a pointer by 
shifting it feft 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


extern volatllé const unsigned char lo_t_prmtv_code 81/129 t conn ind 
83/131 ¢ conn conf 
85/133 t data Ind 
89/137 t expd data ind 
8f/143 t disconn Ind 
93/145 t debug ind 
93/147 t unit data Ind 
95/149 t error report ind 
99/153 t mgt facllity Ind 


OSt primitlve code recelved at 
Layer 5 In a PDU from Layer 4. 
Line Setup configured for 
emulate mode only. 


extern volatile const unsigned char m_lo_t_prmtv_code 84/132 td t data ind 
, 85/133 rd t data Ind 
68/136 td t expd data Ind 
89/137 rd t expd data Ind 
94/148 td t unit data Ind 
95/149 rd t unlit data Ind 


OSI primitive code recelved at 
Layer 5 In a PDU from Layer 4. 
Line Setup configured for 
emulate or monitor mode. 
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Table 66-6 (continued) 


Type 


Variable Value (hex/decima!) 


Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern yolatite unsigned short 
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lo_t_prmty_path 0-8 


m_{to_t_prmtv_path 0-8 


lo_t_Il_buff 


m_lo_t_ll_buff 


lo_t_sdu 


m_lo_t_sdu_offset 


m_lo_t_sdu_size 


up_s_pdu_seg 


Path number received at Layer 
5 In a PDU from Layer 4. Line 
Setup configured for emulate 
mode only. 


Path number recelved at Layer 

5 In a POU from Layer 4. Line 

Setup configured for emulate or 
moniter mode. 


Interlayer-buffer number (an 
IAPX-286 segment number) 
recelved at Layer 5 In a PDU 
from Layer 4, This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 


interlayer-butfer number (an 
iAPX-286 segment number) 
recelved at Layer 5 In a PDU 
from Layer 4. This segment 
number can be converted to a 
pointer by shifting It teft 16 bits. 
Line Setup configured for 
emulate or monitor mode. 


In OSI primitlve received at 
Layer 5 from Layer 4, the offset 
to where the service data unlit 
begins. Line Setup configured 
for emulate mode only. 


In OSI primitlve recelved at 
Layer 5 from Layer 4, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 


Size of the service data unit In 
an Interlayer-message buffer. 
Recelved at Layer 5 from Layer 
4. Same as data_fength Ina 
PDU. Line Setup configured for 
emulate or monitor mode. 


OSI primitive data unlit (PDU) 
|APX-286 sagment number 
received at Layer 5 from Layer 
6, Thls segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 
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Table 66-6 (continued) 


Type 


Variable 


Value (hex/decimal) Meaning 


extern volatile const unsigned char 


extern Volatile const unsigned ohar 


extern volatile unsigned short 


extern volatile unsigned short 


extern unsigned long 


up_s_prmtv_code 


up_s_prmtv_path 


up_s_ll_buff 


up_s_sdu 


I5_tlck_count 


a0/160 
a2/162 
a4/164 
a8/168 
ac/172 
ae/174 
bO/176 
b2/178 
b8/184 


8 conn req . 

8 conn resp 

s data req 

9 expd data req 
8 release req 

@ release resp 

s debug req 

8 unlit data req 
mgt faclilty req 


OS! primitive code recelved at 
Layer 5 In a PDU from Layer 6. 
Line Setup configured for 
emulate mode only. 


Path number recelved at Layer 
§ Ina PDU from Layer 6. Line 
Setup configured for emulate 
mode only. 


Interlayer-buffer number (an 
IAPX-286 segment number) 
recelved at Layer 5 In a PDU 
from Layer 6, This segment 
number can be converted to a 


pointer by shifting It left 16 bits. 


Line Setup configured for 
emulate mode only. 


Offset to the start (header 
node) of the service data unit In 
an Interlayer-message buffer, 
Received at Layer 5 from Layer 
6. Same as data_start_offset In 
a PDU. Line Setup configured 
for emulate mode only. 


32-bit /7_tick_count stored In 
header of most recent IL buffer 
passed up to Layer 5. 
Preserves at each layer the 
orlginal tlme when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 
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Table 66-7 
Layer 6 OSI Variables 


Type Variable Value (hex/decimal) Meaning 


extern event lo_s_prmty True when an OSI primitive Is 
recelved at Layer 6 from Layer 
5. Line Setup configured for 
emulate mode only. 


extern event m_lo_s_prmtv True when an OSI primitive le 
recelved at Layer 6 from Layer 
5. Line Setup configured for 
emutate or monitor mode. 


extern event up_Pp_prmty True when an OS! primitive fe 
recelved at Layer 6 from Layer 
7. Line Setup configured for 
emulate mode only, 


extern volatile unsigned short lo_s_pdu_seg OSI primitlve data unit (PDU) 
IAPX-286 segment number 
received at Layer 6 from Layer 
5. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only, 


extern volatile unsigned short m_lo_s_pdu_seg OS! primitive data unlt (PDU) 
jAPX-286 segment number 
recelved at Layer 6 from Layer 
5. This segment number can 
be corverted to a polnter by 
shifting It feft 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


extern volatile const unsigned char jo_s_prmtv_code ai/i64 8 conn ind 
a3/163 s conn conf 
a5/165 s data Ind 
a9/169 8 expd data ind 
ad/173 s release Ind 
af/175 s release conf 
b1/177 s debug Ind 
b3/179 s unit data Ind 
b5/181 § error report ind 
b9/185 s mgt facility Ind 


OS} primitive code received at 
Layer 6 In a PDU from Layer 5. 
Line Setup configured for 
emulate mode only. 


extern volatile const unsigned char m_lo_s_prmtv_code a4/164 td s data Ind 
a5/165 rd s data Ind 
a8/168 td s expd data Ind 
a9/169 rd s expd data ind 
b4/180 td s unit data Ind 
b5/181 rds unit data Ind 


OSI primitive code received at 
Layer 6 In a PDU from Layer 5. 
Line Setup configured for 
emulate or monitor mode. 
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Table 66-7 (continued) 


Type 


Variable Value (hex/decimal) 


Meaning 


extern volatile const unsigned char 


extern volatiie const unsigned char 


extern Volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern votatile unsigned short 


extern volatile unsigned short 
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lo_s_prmty_path 0-8 


m_lo_s_prmtv_path 0-8 


lo_s_Il_buff 


m_lo_s_Il_buff 


fo _s_sdu 


m_to_s_sdu_offset 


m_lo_s_sdu_size 


up_p_pdu_seg 


Path number recelved at Layer 
6 In a PDU from Layer 5. Line 
Setup configured for emulate 
mode only. 


Path number recelved at Layer 
6 in a PDU from Layer 5. Line 
Setup configured for emulate or 
monitor mode. 


Interlayer-buffer number {an 
JAPX-286 segment number} 
reosived at Layer 6 In a POU 
from Layer 6. This segment 
number can be converted to a 
pointer by shifting it left 16 bits. 
Line Setup configured for 
emulate mode only, 


interlayer-buffer number (an 
IAPX-286 segment number) 
recelved at Layer 6 in a PDU 
from Layer 5. This segment 
number can be converted to a 
pointer by shifting it left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 


tn OS! primitive recelved at 
Layer 6 from Layer &, the offeet 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 


In OSI primitive received at 
Layer 6 from Layer 5, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 


Size of the service data unit In 
an Interlayer-message buffer. 
Recelved at Layer 6 from Layer 
5. Same as data_length Ina 
PDU. Line Setup configured for 
emulate or monitor mode. 


OSI primitive data unit (PDU) 
1APX-286 segment number 
received at Layer 6 from Layer 
7. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup conflgured for emulate 
mode only. 
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Table 66-7 (continued) 


Type Variable Value (hex/decimal) Meaning 

extern volatile const unsigned char up_p_prmtv_code c0/192 p conn req 
02/194 p conn resp 
c4/196 p data req 
8/200 p expd data req 
oc/204 P release req 
ce/206 Pp release resp 
d0/208 p debug req 
d2/210: Pp unit data req 
d8/216 Pp mgt facility req 


OSI primitive code recelved at 
Layer 6 from Layer 7 In a PDU. 
Line Setup configured for 
emutate mode only. 


extern Volatile const unsigned char up_p_prmty_path 0-8 Path number recelved at Layer 
6 from Layer 7 Ina PDU. Line 
Setup configured for emulate 
mode only. 


extern volatile unsigned short up_p_lil_buff Interlayer-buffer number (an 
IAPX-286 segment number) 
recelved at Layer 6 from Layer 
7 Ina PDU, This segment 
number can be converted to a 
pointer by shifting it left 16 bite. 
Line Setup configured for 
emulate mode only. 


extern volatile unsigned short up_p_sdu Offset to the start (header 
noda) of the service data unit In 
an interlayer-message buffer. 
Received at Layer 6 from Layer 
7. Same as data_start_offset In 
a PDU. Line Setup configured 
for emulate mode only. 


extern unsigned long I6_tlck_count 32-bit /1_tick_count stored In 
header of most recent IL buffer 
passed up to Layer 6. 
Preserves at each layer the 
orlginal time when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 
configured for emutate or 
monitor mode. 
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Table 66-8 
Layer 7 OS! Variables 


Type Variable Value (hex/decimal) Meaning 


extern event fo_p_prmtv True when an OSI primitive is 
recelved at Layer 7 from Layer 
6. Line Setup configured for 
emulate mode only, 


extern event m_lo_p_prmty True when an OSI primitive Is 
recelved at Layer 7 from Layer 
6. Line Setup configured for 
emulate or monitor mode. 


extern Volatile unsigned short lo_p_pdu_seg OSI primitive data unit (PDU) 
IAPX~286 segment number 
recelved at Layer 7 from Layer 
6. This segment number oan 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 


extern volatile unsigned short m_lo_p pdu_seg OSI primitive data unlt (PDU) 
IAPX-286 segment number 
recelved at Layer 7 from Layer 
6. This segment number can 
be converted to a polnter by 
shifting It left 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


extern volatile const unsigned char lo_p_prmtv_code 01/193 p conn ind 
03/195 p conn conf 
c5/197 Pp data ind 
69/201 p expd data Ind 
cd/205 p release ind 
cf/207 p release conf 
d1/209 p debug Ind 
d3/211 p unit data Ind 
d5/213 p error report ind 
9/217 P mgt facillty Ind 


OSI primitlve code received at 
Layer 7 in a PDU from Layer 6. 
Line Setup configured for 
emulate mode only. 


extern volatile const unsigned char m_lo_p_prmtv_code c4/196 td p data Ind 
05/197 rd p data Ind 
¢8/200 td p expd data Ind 
9/201 rd p expd data Ind 
4/212 td p unlt data Ind 
5/213 rd p unit data Ind 


OSI primitive code recelved at 
Layer 7 In a PDU from Layer &. 
Line Setup configured for 
emulate or monitor mode. 


extern voiatlle const unsigned char lo_p_prmtv_path 0-8 Path number recelved at Layer 
a 7 In a PDU from Layer 6. Line 
Setup configured for emulate 
mode only. 
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Table 66-8 (continued) 


Type Variable Value (hex/decimal) Meaning 


extern volatile const unsigned char m_!o_p_prmtv_path 0-8 Path number recelved at Layer 
7 In a PDU from Layer 6. Line 
Setup configured for ernulate or 
monitor mode. 


extern volatile unsigned short to_p_ll_buff Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 7 In a PDU 
from Layer 6. This segment 
number can be converted to a 
polnter by shifting it left 16 bits. 
Line Setup configured for 
emulate mode only. 


extern volatile unsigned short m_lo_p_Ii_buff Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 7 In a PDU 
from Layer 6. This segment 
number can be converted to a 
polnter by shifting It teft 16 bits. 
Line Setup configured for 
emulate or monitor mode. 


extern volatile unsigned short lo_p_sdu In OS! primitive recelved at 
Layer 7 from Layer 6, the offset 
to where the service data unit 
begins. Line Setup configured 
for ernulate mode only. 

extern volatile unsigned short m_lo_p_sdu_offset In OSI primitive received at 
Layer 7 from Layer 6, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

extern volatile unsigned short m_lo_p_sdu_size Size of the service data unit In 
an Interlayer-message buffer. 
Recelved at Layer 7 from Layer 
6. Same as data_length Ina 
PDU. Line Setup configured for 
emulate or monitor mode, 


extern unsigned long I7_tIck_count 32-bit /1_tick_count stored In 
header of most recent iL buffer 
passed up to Layer 7. 
Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 


a 


66.3 Routines 


OSI routines available at each layer make sending primitives to a layer above or 
below possible (see Figure 66-3). The routine name and its arguments provide the 
same information as the softkey selections on the Protocol Spreadsheet. (In the early 
phases of compiling the program, the C translator uses the routines to convert the 
spreadsheet softkey-token primitives into C.) All routines are protocol-independent. 
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(A) Layer-Independent OSI Routines 


The following interlayer buffer service routines operate at any layer, regardless of 
protocol (or in the absence of a protocol package). 


_get_il_msg_buff 
Synopsis 


extern void _get_il_msg_buff(buffer_number_ptr, maintain_bit_ptr); 


unsigned short * buffer_number_ptr; 
unsigned short * maintain_bit_ptr; 


Description 

The _get_il_msg_buff routine gets a free interlayer message buffer from the pool 
and returns the buffer number to the caller for use in subsequent calls to other 
interlayer buffer services. It also returns a maintain bit for use in the freeing 
operation. 


Inputs 

The first parameter is a pointer to the location where the buffer number is to be 
stored, The buffer number that is returned is actually an iAPX-286 segment 
number which can be converted to a pointer by shifting it 16 bits to the left. If 
there is no free buffer available, the routine will wait for one to become 
available. 


The second parameter is a pointer to the location where the maintain bit will be 
stored. Since it must be used in the freeing operation, the maintain bit value 
should not be modified. The zero bit in this variable indicates your maintain 


bit. 
Example 


The variables in which the returned buffer number and maintain bit will be 
stored must be declared. When calling the routine, reference the addresses of 
these variables. 


{ 


unsigned short il_buffer_number; 
unsigned short retay_baton; 


} 
LAYER: 4 
STATE: get_a_buffer 
CONDITIONS: KEYBOARD * " 
ACTIONS; 


_get_ll_msg_buff(&il_buffer_number, &relay_baton); 


The routine will get a buffer number and store it in variable i!_buffer_number. 
It will also return a maintain bit and store it in variable relay_baton. 


66-32 JUL '80 


66_ OS! 


JUL '90 


_Start_il_buff_list 


Synopsis 


extern vold _start_it_buff_list(il_buffer_number, start_offset_ptr); 
unsigned short il_buffer_number; 
unsigned short * start_offset_ptr; 


ripti 


The _start_il_buff_list routine starts a linked list of text inside an interlayer 
message buffer. The list is made up of a header node and text nodes. The 
header node contains offsets to the first and last text nodes. Each text node 
contains a pointer to the actual text, the length of the text, and the offset to the 
next text node. This routine actually creates the header node inside the 
interlayer message buffer and initializes the first and last text node offsets to 
zero, indicating an empty list. It will return the offset to the list header node for 
use in subsequent list service calls. 


Inputs 


The first parameter is the interlayer message buffer number that will contain the 
list. 


The second parameter is a pointer to the location where the offset to the list 
header will be stored. The returned offset will be zero if there is insufficient 
room in the buffer for the header node and one text node. Otherwise, it is the 
offset from the beginning of the message buffer to the start of the header node. 


To convert the offset into a pointer, shift the buffer number 16 bits to the left 
and add the offset: 


(void *)(((long)il_buffer_number << 16) + data_start_offset); 


Example 


Get a buffer and start a linked list. The variable in which the returned offset 
will be stored must be declared. When calling the routine, reference the address 
of this variable. 


{ 


unsigned short it_buffer_number; 
unsigned short relay_baton; 
unsigned short data_start_offset; 


) 
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STATE: start_a_list 
CONDITIONS: KEYBOARD “ ” 
ACTIONS: 


{ 
get_it_msg_buff(&il_buffer_number, &relay_baton); 
_Starl_il_buff_list(il_buffer_number, &data_start_offset); 


/* See _insert_il_buff_list_ent routine on how information is Inserted in the buffer. */ 


} 


The routine will get the offset to the header node and store it in variable 
data_start_offset. 


_dup_il_buff_list_start 


Synopsis 

extern unsigned short _dup_il_buff_list_start(il_buffer_number, start_offset, 
new_start_offset_ptr); 

unsigned short il_buffer_number; 


unsigned short start_offset; 
unsigned short * new_start_offset_ptr; i : ’ 


Descripti 


This routine duplicates the header node of a pointer list. In order for a layer to 
retain the ability to resend a buffer—that is, to reference again the same list 
header with the same first-node offset—it must keep its own linked list safe from 
data inserted at a layer below. The _dup_il_buff_list_start routine allows the 
lower layer to start its own list. . 


If the lower layer will insert data into the buffer, it need duplicate only the list 
header (“/ist_start”), not the entire list. If the layer will append data to the 
end of the buffer, it must duplicate the complete linked list via the 
_dup_il_buff_list routine. 


Inputs 


The first parameter is the interlayer message buffer number in which the header 
node will be duplicated. 


The second parameter is the offset to the header node to be duplicated. 
The third parameter is a pointer to the location where the offset to the new 


header node will be stored. 


Returns 


This routine returns zero if there is not enough room in the buffer for the 
duplicated header node and at least one list node. 
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Example 


Duplicate the header node of a buffer passed down from Layer 3. 


{ 
extern volatile unsigned short up_di_il_buff; 
extern volatile unsigned short up_dl_sdu; 
unsigned short 12_data_start_offset; 
} 
LAYER: 3 
STATE: message 
CONDITIONS: KEYBOARD * " i 
ACTIONS: OL_DATA REQ “& (FOX) * 
LAYER: 2 
STATE: duplicate_header 
CONDITIONS: DL_DATA REQ 
ACTIONS: 


{ 
_dup_il_buff_list_start(up_dl_it_buff, up_di_sdu, &12_data_start_offset); 


/* See _insert_il_buff_list_ent routine on how information is inserted in the buffer. */ 


) 
_dup_il_buff_list 


Synopsis 


extern unsigned short dup_it_buff_list (il_ pullers number, start_offset, new_start_offset_ptr); 
unsigned short tt_buffer_number; 

unsigned short start_offset; 

unsigned short * new_start_offset_ptr; 


Descripti 


This routine duplicates an entire pointer list. In order for a layer to be able to 
retain the ability to resend a buffer—that is, to reference again the same list 
header with the same first- and last-node offsets—it must keep its own linked 
list safe from data inserted and appended at a layer below. The 
_dup_il_buff_list routine allows the lower layer to have its own list. 


If the lower layer will append data to the buffer, it should duplicate the entire 
linked list. If the layer will only insert data into the buffer, it need only 
duplicate the header node via the _dup_il_buff_list_start routine. 


Inputs 


The first parameter is the interlayer message buffer number in which the list will 
be duplicated. 


The second parameter is the offset to the header node of the list to be 
duplicated. 
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The third parameter is a pointer to the location where the offset to the header 
node for the new list will be stored. 


Returns 


This routine returns zero if the duplication is successful. If there is not enough 
room in the buffer to duplicate the list, one is returned. 


Example 


Duplicate the entire pointer list-of a buffer passed:down from Layer 3. 


{ 
extern volatile unsigned short up_di_il_buff; 
extern volatile unsigned short up_dl_sdu;, 
unsigned short {2_data_start_offset; 
} 
LAYER: 3 
STATE: message 
CONDITIONS: KEYBOARD " ” 
ACTIONS: DL_DATA REQ “5 @FOX))” 
LAYER: 2 
STATE: duplicate_list 
CONDITIONS: DL_DATA REQ 
ACTIONS: 
{ . 
_dup_it_buff_list(up_di_il_buff, up_dl_sdu, &i2_data_start_offset); 
/* See _append_il_buff_list_ent routine on how information is appended to the buffer. */ 


} 
_open_space_in_it_buff 


Synopsis 


extern void _open:space_in_it_buff(il_buffer_number, length, space_offset_ptr); 


unsigned short il_buffer_number; 
unsigned short length; 
unsigned short * space_offset_pir; 


Description 


The _open_space_in_il_buff routine opens up the requested amount of space in 
the specified interlayer message buffer. It returns an offset from the beginning 
of the buffer to the start of the open space. 


Inputs 


The first parameter is the interlayer message buffer number in which space is to 
be made. 
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The second parameter is the amount of space (number of bytes) requested. 


The third parameter is a pointer to the location where the returned offset will be 
stored. The returned offset will be zero if there is insufficient room in the 
buffer. 


To convert the offset into a pointer, shift the buffer number 16 bits to the left 
and add the offset: 


(void *)(((long}it_buffer_number << 16) + available_space_offset); 


Example 


Always open space in the buffer if you are going to copy data (usually header 
information) into the buffer. If you are not going to copy data into the buffer, 
but reference its location in memory outside the buffer (usually user data), you 
do not need to open space. 


The variable in which the returned offset will be stored must be declared. When 
calling the routine, reference the address of this variable. The length may be 
entered as a numeric value, in which case a length variable need not be 
declared. 


For example, a buffer at Layer 3 will have three X.25—-header bytes inserted. 
The call for space to hold the header would look like this: 


{ 
unsigned short it_buffer_number; 
unsigned short retay_baion; 
unsigned short data_start_offset; 
unsigned short avaiiable_space_offset,; 
) 
STATE: det_space 
CONDITIONS: KEYBOARD “ " 
ACTIONS: 
{ 
_get_it_msg_buff(&li_buffer_number, &relay_baton); 
_start_il_buff_list(il_buffer_number, &data_start_offset); 
_open_space_in_il_buff(il_buffer_number, 3, &avaitable_space_offset); 
/* See _insert_it_buff_list_cnt routine on how information {s Inserled in the buffer. */ 


) 


The routine will get the offset to the next available space in the buffer and store 
it in variable available_space_offset. 


Once space has been opened, the buffer-number and available-space variables 
can be converted into an open-space pointer. With this pointer, data can be 
copied into the space. The pointer can then be referenced in an 
_insert_il_buff_list_cnt routine, so that the opened space becomes threaded onto 
the linked list in the IL buffer. See the programming example under 
_insert_il_buff_list_ent. 
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_free_il_msg_buff 


Synopsis 
extern vold _free_il_msg_buff(il_buffer_number, relay_baton); 


unsigned short tl_buffer_number; 
unsigned short relay_baton; 


Descripti 


The _free_il_msg_buff routine returns an interlayer message buffer to the pool of 
free buffers. Before actually returning the buffer to the pool, this routine 
verifies that all maintain bits have been reset, assuring that all users have freed 


this buffer. 


Inputs 


The first parameter is the interlayer-buffer number to be freed. 


The second parameter is the maintain bit associated with the buffer user to be 
freed. 


Example 


See _set_maint_buff_bit routine. 
_set_maint_buff_bit 


Synopsis 


extern vold _set_maint_buff_bit(il_buffer_number, new_bit_pir); 
unsigned Short ll_buffer_number; 
unsigned short * new_bit_ptr; 


Description 


The _set_maint_buff_bit routine sets a new maintain bit for a given interlayer 
message buffer, It returns that bit to the caller to be used in the freeing 
operation. 


The maintain bit allocated in the _get_il_msg_buff routine should be considered 
valid only for the layer at which it was obtained. Once you pass a buffer, the 
maintain bit will hold the buffer at the next layer only until action on it has been 
processed. (In Spreadsheet terms, the buffer will be held until the ACTIONS 
block has been processed in response to the first CONDITIONS block identifying 
the buffer. In any other CONDITIONS block referring to the buffer, the buffer 
will not be found unless an additional maintain bit was set.) The maintain bit 
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eventually will be freed automatically whether or not any action is taken on it at 
the next layer. To hold a buffer at a particular layer, or to continue passing the 
buffer (in either direction), a new maintain bit must be set. The same maintain 
bit cannot be used continuously, since it will be freed after the first process on it 
(an ACTION to send, for example). 


If you wish to keep a buffer available for your use while also sending it to 
another layer, set two maintain bits. One will be used to pass the buffer; the 
other will “maintain” the buffer for other processes. The latter will have to be 
freed via the _free_il_msg_buff routine. 


Inputs 


The first parameter is the interlayer-buffer number in which the new bit will be 
Set. 


The second parameter is a pointer to the location where the returned maintain 
bit will be stored. There are sixteen maintain bits reserved for each interlayer 
buffer. Each bit is identified by a two-byte variable with a single zero. The first 
maintain bit allocated is the least significant, so the value returned is 
hexadecimal FFFE (binary 11111111 11111110). The last maintain bit 
allocated is 7FFF (01111111 11111111). If all the maintain bits are already in 
use, FFFF wiil be returned. 


The maintain bit value should not be modified. It must be used in the freeing 
operation to make sure the buffer is returned to the free buffer pool. 


Example 


The variable in which the returned maintain bit will be stored must be declared. 
When calling the routine, reference the address of this variable. For example, 
you receive a buffer at Layer 2 from Layer 3 (up_di_il_buff) and insert 
information into it. Before passing the buffer to Layer 1, set two maintain bits. 
The one stored in variable maintain_bit will hold the buffer for the purpose of 
repeated resends of the frame, if necessary, and will have to be freed via the 
_free_il_msg_buff routine. When you pass the buffer down, use the bit in 
variable !2_relay_baton. When you resend the frame, set a new resend_baton 
bit and pass that down, still holding maintain_bit in reserve for subsequent 


resends. 


{ 

unsigned short 12_relay_baton; 

unsigned short resend_baton; 

unsigned short maintain_blt; 

extern volatile unsigned short up_d!_il_buff; 
extern volatile unsigned short up_dl_sdu; 
unsigned short {2_data_start_offset; 
unsigned short available_space_offset; 
Static unsigned char 12_data{2} = {Ox01, 0x00); 
int i; 

unsigned char * ptr_12; 
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define make_pir(number, offset) ((void °)(((long)number << 16) + offset}) 


} 
LAYER: 3 
STATE: send_fox_message 
CONDITIONS: KEYBOARD * " 
ACTIONS: DL_DATA REQ “15 "U(FOX))” 
LAYER: 2 
STATE: send_a_buffer 
CONDITIONS: DL_DATA REQ 
ACTIONS: 
{ 
/* See _insert_it_buff_list_ent routine for an explanation of how information is inserted in the 
buffer. */ 
_dup_it_buff_tist_start (up_di_il_buff, up_di_sdu, &12_data_start_offset); 
_open_space_in_il_buff(up_dt_il_buff, 2, &avatiable_space_offset); 
pir_t2 = make_ptr(up_dt_il_buff, available_space_offset); 
for(i = 0; 5 < 2; itt) 
{ 
*ptr_l2 = data_I2{Ii}; 
ptr_l2tt; 
} 
ptr_{2 -=2; 
_lasert_il_buff_list_ent(up_dt_il_buff, 12_data_start_offset, ptr_l2, 2); 
_set_maint_buff_bit(up_dl_it_buff, &maintain_bit); 
_set_maint_buff_bit(up_di_it_buff, &12_relay_baton); 
send_ph_prmtv_betow(up_di_il_buff, t2_relay_baton, !2_data_start_offset, 0, 0x24, 0); 
} 
LAYER: 1 
STATE: resend_buffer 
CONDITIONS: RECEIVE STRING 4F]°s(XXXX1001))" 
ACTIONS: 
{ . 
_set_maint_buff_bit(up_dl_il_buff, &resend_baton); 
t1_il_transmit(up_dt_il_buff, resend_baton, 12_data_start_offset, 1); 
/* See Section 62, Monitor/Transmil Line Data, for an explanation of the t/_ii_transmit 
routine, °/ 
} 
CONDITIONS: RECEIVE STRING “FIACXXxXx0001) * 
ACTIONS: 
{ 
_Sree_il_msg_buff(up_di_il_buff, maintain_bit); 
/* See _free_il_msg_buff for an explanation of this routine. */ 


} 
_insert_il_buff_list_cnt 


Synopsis 

extern unsigned short _Insert_il_buff_list_ent(il_buffer_number, data_start_offset, text_ptr, 
text_length); 

unsigned short il_buffer_number; 

unsigned short data_start_offset; 

unsigned char * text_ptr; 

unsigned Short text_length; 
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Description 
The _insert_il_buff_list_cnt routine inserts a text node at the beginning of a 


linked list of text inside of an interlayer message buffer. It will set the text 
pointer and byte-count in the text node to the values specified. 


Inputs 


The first parameter is the interlayer-buffer number in which the linked list will 
be inserted. 


The second parameter is the offset to the header node for the linked list, from 
the beginning of the buffer. 


The third parameter is a pointer to a text. 


The fourth parameter is the length of the text. 


Returns 


If the insert is successful, a value of 0 is returned; if it is not successful, a value 
of 1 is returned. If you want to check the returned value, do so at the time the 
routine is called, as in the following example at Layers 2 and 3. 


Example 


If text is to be copied into the buffer, a pointer to the text must be declared. If 
not, when calling the _insert_il_buff_list_cnt- routine, reference the address of 
the text. The length of the text may be entered as an integer, in which case a 
length variable need not be declared. 


Always open space in the buffer if you are going to copy data (usually header 
information) into the buffer. If you are not going to copy data into the buffer, 
but reference its location in memory outside the buffer (usually user data), you 
do not need to open space. 


In the following spreadsheet example, an interlayer-buffer number is obtained at 
Layer 5, a header node is created in the buffer, and the address of a fox 
message text (located in memory outside of the buffer) is inserted into a text 
node in the buffer. 


{ 

unsigned short ti_buffer_number; 
unsigned short relay_baton; — 
unsigned short 14_relay_baton 
unsigned short [3_relay_baton; 
unsigned short i2_relay_baton; 
unsigned short data_start_offset; 
unsigned short !2_data_start_offset; 
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unsigned short available_space_offset; 

static unsigned char data{] = “(FOX)”; 

static unsigned char 13_data{3] = {0x10, 0x04, 0x00}; 
Static unsigned char 12_data{2] = {0x01, 0x00}; 
int i; 

int length; 

extern volatile unsigned short up_t_ll_buff; 
extern volaiiie unsigned short up_n_il_buff; 
extern volatile unsigned short up_dt_ll_buff; 
extern volatile unsigned short up_n_sdu; 

extern volatile unsigned short up_dl_sdu; 

extern volatile unsigned short up_t_sdu; 
unsigned char * ptr_13, * ptr_t2; 


/* Whenever make_ptr is encountered, the first parameter wiil be shifted 16 bits 1o the left. 
The second parameter will be added, and the result casi into a pointer. */ 


define make_pir(number, offset) ((void *}(((long)number << 16) + offset)) 
} 
LAYER: § 
STATE; bsgin_message 
CONDITIONS: KEYBOARD * ” 
ACTIONS: 


{ 
_get_il_msge_buff(&il_buffer_number, d&relay_baton); . 
_Start_il_buff_list(it_buffer_number, &data_start_offset); 


/* Do not include the terminating null character in the length determination of a string. */ 
length = sizeof(data) ~ 1; 


/* The address of data outside of the buffer is given for insertion. The data itself is not copied 
into the buffer. The buffer is then passed down to Layer 4 (see send_t_prmtv_below for an 
explanation of this routine). */ 
_insert_il_buff_list_ent(il_buffer_number, data_start_offset, &data{0], length); 
send_t_prmiv_below(it_buffer_number, relay_baton, data_start_offset, 0, 0x84, 0); 


} 


At Layer 4 a new maintain bit is set to use in passing the buffer to Layer 3. 
Since no data is inserted, the same data_start_offset is used (in the form of the 
variable up_t_sdu). The buffer is then passed down to Layer 3 (see 
send_n_prmtv_below for an explanation of this routine). 


LAYER: 4 
STATE: pass 
CONDITIONS: T_DATA_REQ 
ACTIONS: 
{ 
_set_maint_buff_bit(up_t_il_buff, &l4_relay baton); 
send_n_prmtyv_below(up_t_il_buff, l4_relay_baton, up_t_sdu, 0, 0x64, 0); 


} 


At Layer 3, space is opened for an X.25 packet header. A pointer to the 
opened space is created and the data is inserted into the linked list passed down 


from Layer 4. 
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LAYER: 3 
STATE: Insert_and_send 
CONDITIONS: N_DATA_REQ 
ACTIONS: 
{ 
_open_space_in_il_buff(up_n_il_buff, 3, davailable_space_offset); 
ptr_t3 = make_pir(up_n_it_buff, avaitable_space_offset); 


for(i = 0; i < 3; i++) 


*ptr_t3 = 13_data{i}; 
pir_l3++; 


} 


/* The location of the data in the buffer is referenced in the insert routine, 30 the pointer must 
be moved back to the beginning of the opened space. The offset to the Layer 3 header node is 
given in the insert routine. If the insertion is not successful, an alarm will sound and a message 
will be displayed on the prompt line of the screen, */ 
ptr_{3 -=3; 
if(_insert_it_buff_list_ent(up_n_tt_buff, up_n_sdu, ptr_13, 3) t= 0) 
sound_atarm(); 
display_prompt ("Insert failed at Layer 3.”"); 


/* A new maintain bit Js set for passing the buffer. The buffer Is then passed down to Layer 2 
(see send_di_prmtv_below for an explanation of this routine). */ 
_set_maint_buff_bit(up_n_it buff, &l3_relay_baton); 
send_di_prmty_below(up_n_il_buff, i3_relay_baton, up_n_sdu, 0, 0x44, 0); 
} 


At Layer 2, a new linked list is started. The Layer 2 header could be inserted 
into the linked list passed down from Layer 3; but if Layer 3 wants to retain the 
ability to resend a buffer—that is, to reference again the same list header with 
the same first-node offset—it must Keep its own linked list safe from data 
inserted at Layer 2. 


LAYER: 2 
STATE: Insert_more 
CONDITIONS: DL_DATA_REG 
ACTIONS: 
{ 
/* The _dup_Hl_buff_list_start routine allows Layer 2 to start ils own list. Part of this routine 
copies the Layer 3 header into the Layer 2 header node. */ 
_dup_it_buff_list_start(up_dl_il_buff, up_di_sdu, &I2_data_start_offset); 
/* Space is opened In the buffer. A pointer {o this location is created and the data is copled 
into the buffer. */ 
_open_space_in_il_buff(up_dl_il_buff, 2, &avaitable_space_offset); 
ptr_12 = make_ptr(up_di_il_buff, avallable_space_offset); 
for(i = 0; 1 <2; i++) 
{ 
*ptr_12 = 12_data{t]}; 
ptr_l2++; : 
} 


/* The location of the dala in the buffer is referenced in the insert routine, so the pointer must 
be moved back to the beginning of the opened space. The offset to the Layer 2 header node is 
given in the insert routine. if the insertion is not successful, an alarm will sound and a message 


will be displayed on the prompt line of the screen. */ 
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ptr_l2 -=2; 
if(_insert_il_buff_list_ent({up_dl_it_buff, 12_data_start_offset, ptr_i2, 2) 1!= 0) 


sound_alarm(); 
pos_cursor(0, 30); 
displays(“Insert failed at Layer 2.")}; 


/* A new mainiain bit is sel for passing the buffer. The buffer is then passed down to Layer 1 
(see send_ph_prmtv_betow for an explanation of this routine). °/ 


_set_maint_buff_bit(up_di_tt_buff, &12_relay_baton); 
send_ph_prmiv_below(up_di_il_buff, t2_relay_baton, (2_data_start_offset, 0, 0x24, 0); 


The following text will be sent out onto the line and displayed as line data: 


UUL5 UTHE QUICK BROWN FOX JUMPS OVER THE LAZY DOG 0123456749NG) 
_append_Iil_buff_list_cnt 


Synopsis 

extern unsigned short _append_it_buff_list_cnt(il_buffer_number, data_start_offset, text_ptr, 
text_length); 

unsigned short ll_buffer_number; 

unsigned short data_start_offset; 

unsigned char * text_ptr; 

unsigned short text_length; 


Description 


The _append_il_buff_list_cnt routine appends a text node at the end of a linked 
list of text inside of an interlayer message buffer. It will set the text pointer and 
count in the text node to the information provided. 


Inputs 


See _insert_il_buff_list_cnt routine. 


Returns 


See _insert_il_buff_list_cnt routine. 


Example 


Two modifications to the program shown for the _insert_il_buff_list_cnt routine 
are all that is required to make the program work for appending data. The 
changes primarily involve Layer 2 in the example, so we will replicate only that 
portion of the program below. Substitute _append_il_buff_list_cnt for every 
occurrence _insert_il_buff_list_cnt. When data is to be appended in a buffer, 
you should duplicate the entire linked list received from the layer above, not just 
the header node. So also substitute dup_il_buff_list for _dup_il_buff_list_start. 
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LAYER: 2 
STATE: Insert_more 
CONDITIONS: DL_DATA_REQ 
ACTIONS: 
{ 
_dup_il_buff_list(up_dt_it_buff, up_dl_sdu, &12_data_start_offset); 
—open_space_in_il_buff(up_di_ll_buff, 2, &available_space_offset); 
pir_i2 = make_pir(up_dil_ll_buff, available_space_offset); 
for(i = 0; i< 2; itt) 
{ 
“ptr_{2 = 12_data{i]; 
pir_l2+4; 
} 
ptr_l2 -=2; 
if(_append_il_buff_Ust_cnt(up_dt_ii_buff, 12_data_start_offset, ptr_{2, 2) != 0) 
sound_alarm(); 
pos_cursor(0, 30); 
displays(“Insert failed at Layer 2."); 


} 
_set_matnt_buff_bit(up_di_it_buff, &I2_retay_baton); 
send_ph_prmtv_below(up_dl_il_buff, 12_relay_baton, 12_data_start_offset, 0, 0x24, 0); 


The following text will be sent out onto the line and displayed as line data: 


THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG 01234567892. 5% KYA) 


Layer 1 OSI Routines 


OSI data primitives are handled automatically between Layers 1 and 2. In the 
“up” direction, line data is placed in an IL buffer and the associated data 
primitive is given automatically to Layer 2, In the “down” direction, data 
primitives are received at Layer 1 and put out automatically onto the line. 


In the absence of line data, if you want to originate a buffer at Layer 1 and 
send it upward, use the following routine. In primitives being sent down the 
layers, Layer t will automatically send the primitive out onto the line. 


send_ph_to_above 


Synopsis 


extern void send_ph_to_above(il_buffer_number, relay_baton, data_start_offset, size, code, 
path); 

unsigned short il_buffer_number; 

unsigned short relay_baten; 

unsigned short data_start_offset; 

unsigned short size; 

unsigned char code; 

unsigned char path; 
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Descripti 


The send_ph_to_above emulate routine passes a specified interlayer message 
buffer from Layer 1 to Layer 2 in an OSI primitive. Received line data is 
placed in an IL buffer and passed automatically to Layer 2. If you wish to get a 
buffer “manually” at Layer 1 and then pass it up, use this routine. 


Inputs 


The first parameter is the interlayer buffer number returned by the 
_get_il_msg_ buff routine.. 


The second parameter is the returned maintain bit from the _get_il_msg_buff 
routine. As soon as Layer 2 processing on the buffer is completed, the bit is 
automatically freed. 


The third parameter is the returned offset (from the call to _start_il_buff_list) to 
the Layer 1 service data unit in a buffer. 


The fourth parameter is the length of the data in the buffer. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo_ph_prmtv_code in Table 66-3 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. 


Example 


Get a buffer at Layer 1. Assuming X.25 protocol, insert data into the buffer 
and pass it up to Layer 2. 


{ 

unsigned short il_buffer_number; 

unsigned short relay_baton; 

unsigned short data_start_offset; 

unsigned short available_space_offset; 

int length; 

int i; 

static unsigned char data[{] = {Ox01, 0x00, 0x10, 0x04, 0x00, 0x02, Ox01, 0x01}; 
unsigned char * ptr; 


} 
LAYER: 1 
STATE: get_buffer 
CONDITIONS: KEYBOARD * ” 
ACTIONS: 
{ 
_get_il_msg_buff(&il_buffer_number, &retay_baton); 
_Start_il_buff_list(il_buffer_number, &data_start_offset); 
length = sizeof(data); 
_open_space_in_il_buff(il_buffer_number, length, kavailabie_space_offset); 
ptr = (void *) (({(iong)il_buffer_number << 16) + available_space_offset); 
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for(i = 0; 1 < length; i++) 


“ptr = dataft}; 
pirt+; 


 . 
pir-=length; 
_insert_it_buff_list_ent(il_buffer_number, data_stari_offset, ptr, length); 
send_ph_to_above(li_buffer_number, relay_baton, data_start_offset, length, 0x25, 0); 


} 


(C) Layer 2 OSI-Routines.... 


The following routines pass OSI primitives from Layer 2 to either Layer 3 or 
Layer 1. 


send_di_prmtv_above 


Synopsis 


extern void send_di_prmtv_above(il_buffer_number, {2_relay_baton, {2_data_start_offset, size, 
!2_code, path); 

unsigned short il_buffer_number; 

unsigned short I2_relay_baton; 

unsigned short (2_data_start_offset; 

unsigned short size; 

unsigned char {2_code; 

unsigned char path; 


Descripti 


The send_d!_prmtv_above emulate routine passes a specified interlayer message 
buffer from Layer 2 to Layer 3 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 2 from Layer 1, the variable lo_ph_il_buff 
may be used to identify the buffer number. 


The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. \t is used only to pass a received buffer from Layer 2 to 
Layer 3. As soon as Layer 3 processing on the buffer is completed, the bit is 
automatically freed. 


The third parameter is the offset to the Layer 2 service data unit in a received 
buffer. The variable /o_ph_sdu contains the offset to the service data unit when 
the buffer reached Layer 2. The offset must be incremented by the length of 
the Layer 2 header. 
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NOTE: In general, do not modify extern variables, such as 
lo_ph_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after ljo_ph_sdu has been named in the 
argument of the send routine, add the length of the Layer 2 
header, as in the example below. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure—pdu.data_length. Then subtract the length of the 
Layer 2 header: 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo_di_prmtv_code in Table 66-4 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 2 from Layer 1, the variable 
lo_ph_prmtv_path may be used to specify the path number. 


Example 


A buffer is received at Layer 2 from Layer 1. Assuming X.25 protocol, the 
data specific to Layer 2 (the frame header) begins at the SDU offset 
(lo_ph_sdu) and consists of two bytes. Before the buffer is passed up to Layer 3, 
the offset to the SDU and the size of the SDU will be adjusted by two bytes and 
a new maintain bit will be set. 


{ 


struct pdu 
{ 
unsigned char primitive_code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relay_baton; 
unsigned short il_buffer_number; 
unsigned char buffer_contents; 
unsigned short data_start_offset; 
unsigned Short data_length; 
s 
struct pdu * pdu_ptr; 
extern volatile unsigned short lo_ph_pdu_seg; 
extern volatile const unsigned char lo_ph_prmty_path; 
extern volatile unsigned short lo_ph_it_buff; 
extern volatile unsigned short lo_ph_sdu; 
unsigned short i2_relay_baton; 
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LAYER; 2 
STATE: send_buffer_up 
CONDITIONS: PH_ODATA IND 
ACTIONS: 
{ 
pdu_ptr = (void *)((tong)lo_ph_pdu_seg << 16); ° 
_set_maint_buff_bit(to_ph_l_buff, &i2_retay_baton); 
send_di_prmtv_above(lto_ph_il_buff, 12_relay_baton, lo_ph_sdu + 2, 
pdu_ptr->data_length - 2, 0x45, lo_ph_prmtv_path); 


send_m_dl_prmtv_above 


Synopsis 


extern vold send_m_dl_prmtv_above(il_buffer_number, 12_relay_baton, !2_data_start_offset, 
size, [2_code, path); 

unsigned short it_buffer_number; 

unsigned short [2_retay_baton; 

unsigned short |2_data_start_offset; 

unsigned short size; 

unsigned char 12_code; 

unsigned char path; 


Descripti 


The send_m_dl_prmtv_above monitor routine passes a specified interlayer 
message buffer from Layer 2 to Layer 3 in an OSI monitor primitive. 


. Inputs 


See send_d!_prmtv_above. Use the monitor variables m_lo _ ph_il_buff, 
m_lo_ph_sdu_offset, and m_lo_ph_sdu_size as input. Refer to variable 
m_lo_dl_prmtv_code in Table 66-4 for the appropriate primitive code. 


Example 


Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 2 programming block should look like this: 


LAYER: 2 
STATE: send_buffer_up 
CONDITIONS: PH_RD_DATA iND 
ACTIONS: 
{ 
_set_maint_buff_bit(m_io_ph_li_buff, &12_relay_baton); 
send_m_di_prmiv_above(m_lo_ph_ll_buff, !2_relay_baton,m_ lo_ph_sdu_offset + 2, 
m_lo_ph_sdu_size - 2, 0x45, m_lo_ph_prmtv_path); 
} 
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send_ph_prmtv_below 


Synopsis 


extern void send_ph_prmtv_below(il_buffer_number, {2_relay_baton, |2_data_start_offset, size, 
12_code, path); 

unsigned Short li_buffer_number; 

unsigned short 12_relay_baton; 

unsigned short 12_data_start_offset; 

unsigned shori size; 

unsigned char i2_code; 

unsigned char path; 


Description 


The send_ph_prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 2 to Layer 1 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 2 from Layer 3, the variable up_di_il buff 
may be used to identify the buffer number. If the buffer originated at Layer 2, 
use the buffer-number variabie named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 


The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 2 to 
Layer 1. As soon as Layer 1 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 2, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See _insert_il_buff_list_cnt 
routine example at Layer S.) 


The third parameter is the offset to the Layer 2 list header node in the buffer. 
For a buffer which has been received at Layer 2 from Layer 3, the variable 
up_dl_sdu may be used to indicate the offset. 


The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 


layers, 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable ph_prmtv_type in Table 66-2 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 2 from Layer 3, the variable 
up_dl_prmtv_path may be used to specify the path number. 
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Example 


A buffer is received at Layer 2 from Layer 3. No text will be inserted at Layer 
2. (For information on inserting text, see _insert_il_buff_list_cnt routine.) The 
buffer will be passed to Layer 1, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 


{ 
extern volatile unsigned short up_dt_il_buff; 
extern volatile unsigned. short.up.dl_sdu;. 
unsigned shori {2_retay_baton; 
) 
LAYER: 2 
STATE: pass_buffer_down 
CONDITIONS; DL_DATA REQ 
ACTIONS: 


{ 
_Set_maint_buff_bit(up_dt_il_buff, &I2_relay_baton); 


send_ph_prmtv_below(up_di_il_buff, !2_relay_baton, up_di_sdu, 0, 0x24, 0); 
) 


(D) Layer 3 OSI Routines 


The following routines pass OSI primitives from Layer 3 to either Layer 4 or 
Layer 2. 


send_n_prmtv_above 


Synopsis 


extern void send_n_prmtv_above(il_buffer_number, 13_retay_baton, 13_data_start_offset, size, 
13_code, path); 

unsigned short it_buffer_number; 

unsigned short i3_relay_baton; 

unsigned short {3_data_start_offset; 

unsigned short size; 

unsigned char 13_code; 

unsigned char path; 


Description 
The send_n_prmtv_above emulate routine passes a specified interlayer message 


buffer from Layer 3 to Layer 4 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 3 from Layer 2, the variable Jo_dl_il_buff may 
be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 3 to 
Layer 4. As soon as Layer 4 processing on the buffer is completed, the bit is 
automatically freed. 


The third parameter is the offset to the Layer 3 service data unit in a received 
buffer. The variable /o_dl_sdu contains the offset to the service data unit when 
the buffer reached Layer 3. The offset must be incremented by the length of 
the Layer 3 header. 


NOTE: In general, do not modify extern variables, such as 
lo_di_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after /o_di_sdu has been named in the 
argument of the send routine, add the length of the Layer 3 
header, as in the example below. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure—pdu.data_length. Then subtract the length of the 
Layer 3 header. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent, Refer to variable /o_n_prmtv_code in Table 66-5 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 3 from Layer 2, the variable 
lo_dl_prmtv_path may be used to specify the path number. 


Example 


A buffer is received at Layer 3 from Layer 2. Assuming X.25 protocol, the 
header consists of three bytes. The offset to and size of the service data unit 
will be adjusted by three bytes, a new maintain bit will be set, and the buffer will 
be passed up to Layer 4. 


{ 


struct pdu 


unsigned char primitive_code; 
unsigned char path; 

unsigned long parameter; 
unsigned short relay_baton; 
unsigned short il_buffer_number; 
unsigned char buffer_contents; 
unsigned short data_Start_offset; 
unsigned short data_length; 


); 
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Struct pdu * pdu_ptr; 
extern volatile unsigned short lo_dl_pdu_seg; 
extern volatile const unsigned char to_dl_prmtv_path; 
extern volatile unsigned short lo_di_it_buff; 
extern volatile unsigned short lo_dl_sdu; 
unsigned short 13_relay_baton; 
} 
LAYER: 3 
STATE: send_buffer_up 
CONDITIONS: DL_DATA IND 
ACTIONS; 
{ 
pdu_ptr = (vold *)((long)io_dl_pdu_seg << 16);- 
_set_maint_buff_bit(lo_dl_it_buff, &l3_relay_baton); 
send_n_prmiv_above(lo_di_lt_buff, [3_relay_baton, lo_di_sdu + 3, 
pdu_ptr->data_length - 3, 0x65, lo_di_prmtv_path); 


send_m_n_prmtv_above 


Synopsis 

extern vold send_m_n_prmty_above(il_buffer_number, 13_relay_baton, (3_data_start_offset, 
size, 13_code, path); 

unsigned short it_buffer_number; 

unsigned short 13_retay_baton; 

unsigned short 13_data_start_offset; 

unsigned short size; 

unsigned char i3_code; 

unsigned char path; 


Descripti 
The send_m_n_prmtv_above monitor routine passes a specified interlayer 
message buffer from Layer 3 to Layer 4 in an OSI monitor primitive. 


Inputs 


See send_n_prmtv_above. Use the monitor variables m_lo_dl_il_buff, 
m_lo_dl_sdu_offset, and m_lo_dl_sdu_size as input. Refer to variable 
m_lo_n_prmtv_code in Table 66-5 for the appropriate primitive code. 


Example 


Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 3 programming block should look like this: 


LAYER: 3 
STATE: send_buffer_up 
CONDITIONS: DL_RD_DATA IND 
ACTIONS: 


{ 

_set_maint_buff_bit(m_lo_di_il_buff, &I3_relay_baton); 

send_m_n_prmtv_above(m_lto_dt_il_buff, (3_relay_baton, m_lo_dl_sdu_offset + 3, 
m_to_di_sdu_size - 3, 0x65, m_lo_di_prmity_path); 


) 
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send_dli_prmtv_below 


Synopsis 


extern vold send_dl_prmtv_below(il_buffer_number, i3_relay_baton, 13_data_start_offset, size, 
{3_code, path); 

unsigned short il_buffer_number; 

unsigned short {3_relay_baton; 

unsigned short 13_data_start_offset; 

unsigned short size; 

unsigned char 13_code; 

unsigned char path; 


Description 
The send_di_prmiv_below emulate routine passes a specified interlayer message 
buffer from Layer 3 to Layer 2 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 3 from Layer 4, the variable up_n_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 3, use 
the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 


The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit, It is used only to pass a received buffer from Layer 3 to 
Layer 2. As soon as Layer 2 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 3, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See _insert_il_buff_list_cnt 
routine example at Layer 5.) 


The third parameter is the offset to the Layer 3 list header node in the buffer. 
For a buffer which has been received at Layer 3 from Layer 4, the variable 
up_m_sdu may be used to indicate the offset. 


The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_d/_prmtv_code in Table 66-3 for the 


appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 3 from Layer 4, the variable 
up_n_prmtv_path may be used to specify the path number. 
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Example 


A buffer is received at Layer 3 from Layer 4. No text will be inserted at Layer 
3. (For information on inserting text, see _insert_il_buff_list_cnt routine.) The 
buffer will be passed to Layer 2, requiring a new maintain bit to be set. If 

values are entered for the code and path, these variables need not be declared. 


{ 


extern volatile unsigned short up_n_Il_buff; 
extern volatile unsigned short up_n_sdu; 
unsigned short 13_relay_baton; 


) 
LAYER: 3 
STATE: pass_buffer_down 
CONDITIONS; N_DATA REQ 
ACTIONS: 


{ 
_set_maint_buff_bit(up_n_il_buff, &l3_reiay_baton); 


send_dl_prmtv_below(up_n_il_buff, 13_relay_baton, up_n_sdu, 0, 0x44, 0); 
) 


Layer 4 OSI! Routines 


The following routines pass OSI primitives from Layer 4 to either Layer 5 or 
Layer 3. 


send_t_prmtv_above 


Synopsis 

extern void send_t_prmtv_above(il_buffer_number, !4_relay_baton, (4_data_start_offset, size, 
14 code, path); 

unsigned short il_buffer_number, 

unsigned short t4_relay_baton; 

unsigned short 14_data_start_offset; 

unsigned short size; 

unsigned char [4_code; 

unsigned char path; 


Description 


The send_t_prmtv_above emulate routine passes a specified interlayer message 
buffer from Layer 4 to Layer 5 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 4 from Layer 3, the variable lo_n_il_buff may 
be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 4 to 
Layer 5. As soon as Layer S processing on the buffer is completed, the bit is 
automatically freed. 


The third parameter is the offset to the Layer 4 service data unit in a received 
buffer. The variable fJo_n_sdu contains the offset to the service data unit when 
the buffer reached Layer 4. The offset must be incremented by the length of 

the Layer 4 header, if any. 


NOTE: In general, do not modify extern variables, such as 
lo_n_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after /o_n_sdu has been named in the 
argument of the send routine, add the length of the Layer 4 
header, if any. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure—pdu.data_length. Then subtract the iength of the 
Layer 4 header, if any. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable /o_¢ prmtv_code in Table 66-6 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 4 from Layer 3, the variable 
fo_n_prmtv_path may be used to specify the path number. 


Example 


A buffer is received at Layer 4 from Layer 3. The offset to and size of the 
service data unit will be adjusted if needed, a new maintain bit will be set, and 
the buffer will be passed up to Layer 5. 


{ 
struct pdu 

{ 

unsigned char primitive_code; 

unsigned char path; 

unsigned long parameter; 

unsigned short relay_baton; 

unsigned short it_buffer_number; 

unsigned char buffer_contents; 

unsigned short data_start_offset; 

unsigned short data_length; 

; 
struct pdu * pdu_ptr; 
extern yolatile unsigned short lo_n_pdu_seg; 
extern volatile const unsigned char'lo_n_prmtv_path; 
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extern volatile unsigned short to_n_il_buff; 
extern volatile unsigned short lo_n_sdu; 
unsigned short 14_retay_baton; 
} 
LAYER: 4 
STATE: send_buffer_up 
CONDITIONS: N_DATA IND 
ACTIONS: 
{ 
pdu_ptr = (void *)((long)lo_n_pdu_seg << 16); 
_set_maint_buff_bit(to_n_it_buff, &t4_retay_baton); 
send _t_prmtv_above(lo_n_il_buff, l4_retay_baton, lo_n_sdu,pdu_ptr->data_length, 
0x85, to_n_prmtv_path); 
) 


send_m_t_prmtv_above 


Synopsis 

extern void send_m_t_prmtv_above(il_buffer_number, {4_relay_baton, 14_data_start_offset, 
size, 14_code, path); : 

unsigned short it_buffer_number; 

unsigned short i4_relay_baton; 

unsigned short 14_data_start_offset; 

unsigned short size; 

unsigned char {4_code; 

unsigned char path; 


Descripti 


The send_m_t_prmtv_above monitor routine passes a specified interlayer message 
buffer from Layer 4 to Layer 5 in an OSI monitor primitive. 


Inputs 


See send_t_prmtv_above. Use the monitor variables m_lo_n_il_buff, 
m_lo_n_sdu_offset, and m_lo_n_sdu_size as input. Refer to variable 
m_lo_t_prmtv_code in Table 66-6 for the appropriate primitive code. 


Example 


Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 4 programming block should look like this: 


LAYER: 4 
STATE: send_buffer_up 
CONDITIONS: N_RD_DATA IND 
ACTIONS: 


a 

_set_maint_buff_bit(m_lo_n_il_buff, &l4_retay_baton); 

send_m_t_prmtv_above(m_lo_n_il_buff, !4_relay_baton,m_o_n_sdu_offset , 
m_lo_n_sdu_size, 0x85, m_lo_n_prmtv_path); 


} 
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send_n_prmtv_below 


Synopsis 

extern void send_n_prmtv_below(Il_buffer_number, [4_relay_baton, 14_data_start_offset, size, 
!4_code, path}; 

unsigned short t_buffer_number; 

unsigned short 14_relay_baton; 

unsigned short i4_data_start_offset; 

unsigned short size; 

unsigned char l4_code; 

unsigned char path; 


Descripti 


The send_n_prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 4 to Layer 3 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 4 from Layer 5, the variable up_t_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 4, use 
the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 


The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 4 to 
Layer 3. As soon as Layer 3 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 4, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See _insert_il_buff_list_cnt 
routine example at Layer 5.) 


The third parameter is the offset to the Layer 4 list header node in the buffer. 
For a buffer which has been received at Layer 4 from Layer 5, the variable 
up_t_sdu may be used to indicate the offset. 


The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_n_prmtv_code in Table 66-4 for the 


appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 4 from Layer 5, the variable 
up_t_prmty_path may be used to specify the path number. 


JUL ’80 


66_OS! 


JUL '90 


(F) 


Example 


A buffer is received at Layer 4 from Layer 5. No text will be inserted at Layer 
4. (For information on inserting text, see _insert_il_buff_list_cnt routine.) The 
buffer will be passed to Layer 3, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 


{ 


extern volatile unsigned short up_t_il_buff; 


extern volatile unsigned short up_t sdu; 
unsigned short |4_relay_baton; 


} 
LAYER; 4 
STATE: pase_buffer_down 
CONDITIONS: T_DATA REQ 
ACTIONS: 


{ 

_Set_maint_buff_bit(up_t_it_buff, &t4_relay_baton); 
send_n_prmiv_below(up_t_il_buff, i4_relay_baton, up_t_sdu, 0, 0x64, 0); 
} 


Layer 5 OSI Routines 


The following routines pass OSI primitives from Layer 5 to either Layer 6 or 
Layer 4. 


send_s_prmtv_above 


Synopsis 


extern void send_s_prmiv_above(il_buffer_number, {S_relay_baton, 15_data_start_offset, size, 
{S_code, path); 

unsigned short il_buffer_number; 

unsigned short (S_reiay_baton; 

unsigned short 1$_data_start_offset; 

unsigned short size; 

unsigned char I5_code; 

unsigned char path; 


Description t 


The send_s_prmtv_above emulate routine passes a specified inter-layer message 
buffer from Layer 5 to Layer 6 in an OSI primitive. 


Inputs 


The first parameter is the inter-layer buffer number to be sent. For a buffer 
which has been received at Layer 5 from Layer 4, the variable /o_¢_il_buff may 
be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 5 to 
Layer 6. As soon as Layer 6 processing on the buffer is completed, the bit is 
automatically freed. 


The third parameter is the offset to the Layer 5 service data unit in a received 
buffer. The variable /o_¢ sdu contains the offset to the service data unit when 
the buffer reached Layer 5. The offset must be incremented by the length of 
the Layer 5 header, if any. 


NOTE: In general, do not modify extern variables, such as 
fo_t_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after /o_¢_sdu has been named in the argument 
of the send routine, add the length of the Layer 5 header, if any. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure—pdu.data_length. Then subtract the length of the 
Layer 5 header, if any. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable /o_s_prmtv_code in Table 66-7 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 5 from Layer 4, the variable 
lo_t_prmtv_path may be used to specify the path number. 


Example 

A buffer is received at Layer 5 from Layer 4. The offset to and size of the 
service data unit will be adjusted if needed, a new maintain bit will be set, and 
the buffer will be passed up to Layer 6. 


{ 
Struct pdu 
{ 
unsigned char primitive_code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relay_baton; 
unsigned Short il_buffer_number; 
unsigned char buffer_contents; 
unsigned short data_start_offset; 
unsigned short data_length; 
}; 
struct pdu * pdu_ptr; 
extern volatile unsigned short to_t_pdu_seg; 
extern volatile const unsigned char lo_t_prmtv_path; 
extern volatile unsigned short lo_t_il_buff; 
extern volatile unsigned short lo_t_sdu; 
unsigned short 15_relay_baton; : 


66-60 JUL '90 


66 OS! 


LAYER: 5 
STATE: send_buffer_up 
CONDITIONS: T_DATA IND 
ACTIONS: 
{ 
pdu_ptr = (void *) ((iong)lo_t_pdu_seg << 16); 
_set_maint_buff_bit(to_t_il_buff, &15_retay_baton); 
send_s_prmtv_above(lo_t_il_buff, 1S_relay_baton, lo_t_sdu, pdu_ptr->data_length, 
OxaS, lo_t_prmtv_path); 
} 


send_m_s_ prmtv_above 


Synopsis 


extern void send_m_s_prmiv_above(l!_buffer_number, I5_retay_baton, 15_data_start_offset, 
size, [5_code, path); 

unsigned Short it_buffer_number; 

unsigned Short I5_retay_baton; 

unsigned short 15_data_start_offset; 

unsigned short size; 

unsigned char {5_code; 

unsigned char path; 


Description 


The send_m_s_prmtv_above monitor routine passes a specified inter-layer 
message buffer from Layer 5 to Layer 6 in an OSI monitor primitive. 


Inputs 


See send_s_ prmtv_above. Use the monitor m_lo_t_il_buff, m_lo_t_sdu_offset, 


and m_lo_t_sdu_size variables as input. Refer to variable m_lo_s_prmtv_code in 
Table 66-7 for the appropriate primitive code. 


Example 


Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 5 programming block should look like this: 


LAYER: 5 
STATE: send_buffer_up 
CONDITIONS: T_RD_DATA IND 
ACTIONS; 
{ 
_set_maint_buff_bli(m_lo_t_il_buff, &t5_retay_baton); 
send_m_s_prmtv_above(m_lo_t_il_buff, !S_relay_baton,m_ lo_t_sdu_offset, 
m_lo_t_sdu_size, Oxa5, m_lo_t_prmtv_path); 


} 
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send_t_prmtv_below 


Synopsis 

extern void send_t prmtv_below(i_buffer_number, {5_retay_baton, {5_data_start_offset, size, 
{5_code, path); 

unsigned short il_buffer_number; 

unsigned short (5_relay_baton; 

unsigned short {S_data_start_offset; 

unsigned short size; 

unsigned char |5_code; 

unsigned char path; 


Descripti 


The send_t_prmtv_below emulate routine passes a specified inter-layer message 
buffer from Layer 5 to Layer 4 in an OSI primitive. 


Inputs 


The first parameter is the inter-layer buffer number to be sent. For a buffer 
which has been received at Layer 5 from Layer 6, the variable up_s_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 5, use 
the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 


The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass.a received buffer from Layer 5 to 
Layer 4. As soon as Layer 4 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 5, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See _insert_il_buff_list_cnt 
routine example at Layer 5.) 


The third parameter is the offset to the Layer 5 list header node in the buffer. 
For a buffer which has been received at Layer 5 from Layer 6, the variable 
up_s_sdu may be used to indicate the offset. 


The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_t_prmtv_code in Table 66-5 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 5 from Layer 6, the variable 
up_s_prmty_path may be used to specify the path number. 
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Example 


A buffer is received at Layer 5 from Layer 6, No text will be inserted at Layer 
5. (For information on inserting text, see _insert_il_buff_list_cnt routine.) The 
buffer will be passed to Layer 4, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 


{ 
extern volatile unsigned short up_s il buff; 
extern volatile unsigned short up_s_sdu; 
unsigned short {5_relay_baton; 
} 
LAYER: 5 
STATE: pass_buffer_down 
CONDITIONS: S_DATA REQ 
ACTIONS: 
{ . 
_set_maint_buff_bit(up_s_il_buff, &idS_relay_baton); 


send_t_prmtv_below(up_s_ii_buff, t5_relay_baton, up_s_sdu, 0, 0x84, 0); 
} 


(G) Layer 6 OS! Routines 


The following routines pass OSI primitives from Layer 6 to either Layer 7 or 
Layer 5. 


send_p_prmtv_above 


Synopsis 

extern void send_p_prmtv_above(il_buffer_number, l6_relay_baton, 16_data_Start_offset, size, 
16_code, path); 

unsigned short il_buffer_number; 

unsigned short i6_relay_baton; 

unsigned short i6_data_start_offset; 

unsigned short size; 

unsigned char [6_code; 

unsigned char path; 


Description 

The send_p_prmtv_above emulate routine passes a specified interlayer message 
buffer from Layer 6 to Layer 7 in an OSI primitive. 

Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 6 from Layer 5, the variable /o_s_il_buff may 
be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 6 to 
Layer 7. As soon as Layer 7 processing on the buffer is completed, the bit is 
automatically freed. 


The third parameter is the offset to the Layer 6 service data unit in a received 
buffer. The variable /o_s_sdu contains the offset to the service data unit when 
the buffer reached Layer 6. The offset must be incremented by the length of 
the Layer 6 header, if any. 


NOTE: In general, do not modify extern variables, such as 
lo_s_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after Jo_s_sdu has been named in the 
argument of the send routine, add the Jength of the Layer 6 
header, if any. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure—pdu.data_length. Then subtract the length of the 
Layer 6 header, if any. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo_p_prmtv_code in Table 66-8 for the 
appropriate primitive code. : 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 6 from Layer 5, the variable 
lo_s_prmtv_path may be used to specify the path number. 


Example 


A buffer is received at Layer 6 from Layer 5. The offset to and size of the 
service data unit will be adjusted if needed, a new maintain bit will be set, and 
the buffer will be passed up to Layer 7. 


{ 


struct pdu 
{ 
unsigned char primitive_code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relay_baton; 
unsigned short li_buffer_number; 
unsigned char buffer_contents; 
unsigned short data_start_offset; 
unsigned short data_length; 
}; 
struct pdu * pdu_ptr; 
extern volatile unsigned short lo_s_pdu_seg; 
extern volatile const unsigned char lo_s_prmtv_path; 
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extern volatile unsigned short lo_s_il_buff; 


extern volatile unsigned short lo_s_sdu; 
unsigned short {6_retay_baton; 


} 
LAYER: 6 
STATE: send_buffer_up 

CONDITIONS: S_DATA IND 

ACTIONS: 

{ 

pdu_ptr = (vold *)((long)lo_s_pdu_seg << 16); 

_set_maint_buff_bit{lo_s_il_buff, &l6_relay_baton); 

send_p_prmiv_above(lo_s_il_buff, t6_relay_baton, fo_s_sdu, pdu_ptr->data_length, 

OxcS, lo_s_prmty_path); 
} 


send_m_p_prmtv_above 


Synopsis 

extern vold send_m_p_printv_above(il_buffer_number, i6_relay_baton, (6_data_start_offset, 
size, 16_code, path); 

unsigned short il_buffer_number; 

unsigned short 16_relay_baton; 

unsigned short 16_data_start_offset; 

unsigned short size; 

unsigned char (6_code; 

unsigned char path, 


Descripti 


The send_m_p_prmtv_above monitor routine passes a specified interlayer 
_ message buffer from Layer 6 to Layer 7 in an OSI monitor primitive. 


Inputs 


See send_p_prmtv_above. Use the monitor variables m_/o_s_il_buff, 
m_lo_s_sdu_offset, and m_lo_s_sdu_size as input. Refer to variable 
m_lo_p_prmtv_code in Table 66-8 for the appropriate primitive code. 


Example 


Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 6 programming block should look like this: 


LAYER: 6 
STATE: send_buffer_up 
CONDITIONS: S_RD_DATA IND 
ACTIONS: 
{ 
_set_maint_buff_bit(m_lo_s_l_buff, &I6_relay_baton); 
send_m_p_prmtv_above(m_to_s_il_buff, 16_retay_baton,m_ lo_s_sdu_offset, 
m_lo_s_sdu_size, Oxe5, m_lo_s_prmtv_path); 


} 


JUL '90 66-65 


INTERVIEW 7000 Serles Advanced Programming: ATLC-107-951~108 


66-66 


send_s_prmtv_below 


Synopsis 


extern vold send_s_prmtv_below(il_buffer_number, 16_relay_baton, 16_data_start_offset, size, 
!6_code, path); 

unsigned short tl_buffer_number; 

unsigned short l6_relay_baton; 

unsigned short 16_data_start_offset; 

unsigned short size; 

unsigned char l6_code; 

unsigned char path; 


Description 


The send_s_prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 6 to Layer S in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 6 from Layer 7, the variable up_p_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 6, use 
the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 


The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 6 to 
Layer 5. As soon as Layer 5 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 6, use the maintain bit 
variable named in the _get_il_msg buff routine. (See _insert_il_buff_list_cnt 
routine example at Layer 5.) 


The third parameter is the offset to the Layer 6 list header node in the buffer. 
For a buffer which has been received at Layer 6 from Layer 7, the variable 
up_p_sdu may be used to indicate the offset. 


The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
ayers. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_s_prmtv_code in Table 66-6 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 6 from Layer 7, the variable 
up_p_prmtv_path may be used to specify the path number. 
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Example 


A buffer is received at Layer 6 from Layer 7. No text will be inserted at Layer 
6. (For information on inserting text, see _insert_il_buff_list_cnt routine.) The 
buffer will be passed to Layer 5, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 


{ 


extern volatile unsigned short up_p_ll_buff; 
extern volatile unsigned short up_p_sdu; 
unsigned short (6_relay_baton; 
) 
LAYER: 6 
STATE: pass_buffer_down 
CONDITIONS: P_DATA REQ 
ACTIONS: 


{ 
_set_maint_buff_bit(up_p_il_buff, &l6_retay_baton); | 
send_s prmtv_betow(up_p_il_buff, 16_relay_baton, up_p_sdu, 0, Oxa4, 0); 


} 


Layer 7 OS! Routines 


send_p_prmtv_below 


Synopsis 
extern void send_p_prmtv_below(il_buffer_number, relay_baton, data_start_offset, size, code, 
path); 
unsigned short il_buffer_number,; 
unsigned short relay_baton; 
unsigned short data_start_offset; 
unsigned short size; 
unsigned char code; 
unsigned char path; 


ripti 
The send_p_prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 7 to Layer 6 in an OSI primitive. 


Inputs 


The first parameter is the interlayer buffer number to be sent, Use the 
buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 


The second parameter is the returned maintain bit from the cail to 
_get_il_msg_buff. 
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The third parameter is the returned offset (from a call to _start il_buff_list) to 
the Layer 7 list header node in the buffer. 


The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_p_prmtv_code in Table 66-7 for the 
appropriate code. 


The sixth parameter is the path number along which the buffer will be sent, 


Example 


A buffer is obtained at Layer 7. The buffer will be passed to Layer 6, without 
any data inserted. (For information on inserting text, see _insert_il_buff_list_cnt 
routine.) If values are entered for the code and path, variables for code and 
path need not be declared. 


unsigned short il_buffer_number; 
unsigned short data_start_offset; 
unsigned short relay_baton; 


} 
LAYER: 7 
STATE: pass_buffer_down 
CONDITIONS: KEYBOARD “* ” 
ACTIONS: 
{ 
_get_il_msg_buff(&il_buffer_number, &relay_baton); 
_Start_il_buff_list(il_buffer_number, .&data_start_offset); 
send_p_prmtv_below(il_buffer_number, relay_baton, data_start_offset, 0, Oxc4, 0); 
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The PRINTER port is a serial interface through which the programmer may direct output from 
the INTERVIEW to a printer. The printer. port.is located at the rear of the INTERVIEW 
between the REMOTE RS-232 and AUXILIARY ports. 


NOTE: Before directing output to the printer port, configure the 
Printer Setup menu as explained in Section 15.2. 


Each spreadsheet PRINT action or call to one of the C print routines causes output to be 
added to a queue of unprinted text in the print buffer. If not doing so already, the print 
server also begins to poll the print buffer for text to print. As long as there is unprinted text 
in the buffer, the print server polls the buffer, removes text, and sends it to the printer port 
of the INTERVIEW. Use the _print_buffer structure to monitor the flow of text in and out 
of the print buffer. 


Use any of the four C print routines explained in this section to add text to the print buffer. 
Three of them—printc, printf, and prinis—are similar to the displayc, displayf, and displays 
routines which direct output to the Display Window. See Section 64.3(C). With the 
set_print_header routine, you determine the heading which will appear at the top of each 
printed page. One other routine, sprintf, writes output to a string. The string can then be 
referenced in subsequent calls to printf. (You may also use the string named in sprintf in 
calls to displayf, tracef, or fprintf.) 


67.1 Structures 


Refer to Table 67-1 for the structure of the print buffer. Compare _print_buffer.in 
with _print_buffer.out to determine whether or not the print buffer has emptied. 
When the values of these two variables are equal, the buffer is empty. 


NOTE: Consider the variables in the _print_buffer structure 
read-only variables. In general, do not modify extern structures 
or variables which may be updated by other processes. 


At times, processes may add transactions to the print buffer more quickly than the 
print server takes them out. If a process cannot add to the buffer without overwriting 
unprinted text, a buffer overrun occurs. When your INTERVIEW is configured for 
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data playback, you can minimize print-buffer overruns by periodically suspending 
playback and allowing the print server to empty the buffer. In judging how often to 
suspend playback, keep in mind the following points: 1) In general, the more 
conditions a program has that trigger print actions, the more frequently playback 
should be suspended. 2) When planning to print Run-mode buffers, remember that 
the faster the playback speed, the quicker the print buffer fills. 


Table 67-1 
Print Structures 


Type Variable Value (hex/decimal) Meaning 
Structure Name: print_buffer Structure of the print buffer. Dectared as type 
struct. 
unsigned short in a-207/10-8199 offset into the print buffer (from the physical 


beginning of the buffer) to the location where 
next transaction text will be added. Advances 
with each spreadsheet PRINT aotion or call to a 
C print routine. When /n equals out, the print 
buffer Js empty. 


unsigned short out a-207/10-8199 offset Into the print buffer (from the physicat 
beginning of the buffer} to the last transaction 
text printed from the buffer. Advances each 
time text Is actually sent out the printer port of 
the INTERVIEW. When out equals fn, the print 
buffer Is empty. 


unsigned short buffer_end 209/8201 offset to the physical end of the print 
buffer—I.e., to the end of the array named 
buffer (see below) 


unsigned short lock when process Is printing, locks out other 
processes from accessing the print buffer 
char polling 0 print server ts not polling 
non-zero print server is polling print buffer for text to print 
char overrun 0 print buffer Is not in overrun state 
non-zero print buffer Is in overrun state—lI.e., a process 


attempting to add text to the print buffer can't 
because unprinted text in the buffer would be 

overwritten. Following message will appear on 
printout: “print buffer overrun has occurred." 


char buffer [8192] array of text transactions 
Structure Name: _print_buffer An Instance of the print_buffer structure, 


declared as type extern struct print_buffer. Use 
the variables contalned In this structure to 
monitor flow of text in and out of the print buffer. 
Reference structure variables as follows: 
_print_bulfer.in, 


a  ———— 
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The following example shows how you might use a TIMEOUT condition to check the 
print buffer periodically. Each time the timeout expires, the program determines 
whether or not the buffer is half full. If so, playback is suspended. If the buffer is 
only one-quarter full, playback is resumed. (Other conditions in the program, not 
illustrated here, would cause print actions to send output to the print buffer.) 


{ 

define PRINT_BUFFER_SZ 8192 

define STOP_POINT (PRINT_BUFFER_SZ/2) 
define START_POINT (PRINT_BUFFER_SZ/4} 


) 
LAYER; 1 
{ 


struct print_buffer 


unsigned short tn; 
unsigned short out; 
unsigned short buffer_end; 
unsigned short lock; 
char polling; 
char overrun; 
}s 
extern struct print_buffer _print_buffer; 
int ernt_buffer_sz; 


} 
STATE: check_print_buffer 
CONDITIONS: ENTER_STATE 
ACTIONS: TIMEOUT ck_buffer RESTART 0.01 
CONDITIONS: TIMEOUT ck_buffer 
ACTIONS: 
{ 
ernt_buffer_sz = (({_print_buffer,in + PRINT_BUFFER_SZ) - _print_buffer.out) % 
PRINT_BUFFER_SZ; 
if(ernt_buffer_sz > STOP_POINT) 
suspend_rerd_play(); 
else if(crnt_buffer_sz < START_POINT) 
Start_rerd_play(); 


} 
TIMEOUT ck_buffer RESTART 0.01 


67.2 Variables 


There are no variables associated exclusively with print functions. 
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Routines 


printc 


Synopsis 


extern void printe(character); 


const char character; 


ripti 


The printc routine outputs a single ASCII character to the print buffer for printing, 
converting the value provided as the argument into its ASCII equivalent. Decimal 
and octal values are converted to hexadecimal format before the ASCII equivalent is 
sought. 


Inputs 


The only parameter is a numerical value. The value may be given as a hexadecimal, 
octal, or decimal constant; as an alphanumeric constant inside of single quotes; or as 
a variable. A hexadecimal value must be preceded by the prefix 0x or 0X; an octal 
value must be preceded by the prefix 0. If no prefix appears before the input, the 
number is assumed to be decimal. Valid numeric entries are 00 to 127, decimal. An 
alphanumeric character placed between single quotes will be output as is to the 
printer. 


Example 


The printc entries on the left output the printed character given on the right: 


printe(‘a’); 
prinic(65); 
printc(Ox65); 
printc(065); 


ue >» Bw 


printf 
Synopsis 


extern int printf(format_ptr, ... ); 
const char * format_ptr; 


Description 


The printf routine writes output to the print buffer for printing, under control of the 
string pointed to by format_ptr that specifies how subsequent arguments are converted 
for output. If there are insufficient arguments for the format, the behavior is 
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undefined. If the format is exhausted while arguments remain, the excess arguments 
are evaluated but otherwise ignored. The printf routine returns when the end of the 
format string is encountered. 


Inputs 


The format is composed of zero or more directives: ordinary characters (not %), 
which are copied unchanged to the output stream; and conversion specifications, each 
of which results in fetching zero or more subsequent arguments. Each conversion 
specification is introduced by the character %. After the %, the following appear in 
sequence: 


Zero or more flags that modify the meaning of the conversion specification. 
The flag characters and their meanings are: 


- The result of the conversion will be left-justified within the field. 


+ The result of a signed conversion will always begin with a plus or minus 
sign. 


space If the first character of a signed conversion is not a sign, a space will be 
prepended to the result. If the space and + flags both appear, the space 
flag will be ignored. 


# The result is to be converted to an “alternate form.” Ford, i, u, ¢, and 
s conversions, the flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a zero. For x (or X) 
conversion, a nonzero result will have 0x (or 0X) prepended to it. 


An optional decimal integer specifying a minimum field width. If the converted 
value has fewer characters than the field width, it will be padded on the left (or 
right, if the left adjustment flag, described above, has been given) to the field 
width. The padding is with spaces unless the field width integer starts with a 
zero, in which case the padding is with zeros. 


An optional precision that gives the minimum number of digits to appear for the 
d, i, 0, u, x, and X conversions, or the maximum number of characters to be 
written from an array in an s conversion. The precision takes the form of a 
period (.) followed by an optional decimal integer; if the integer is omitted, it is 
treated as zero. The amount of padding specified by the precision overrides that 
specified by the field width. 


An optional h specifying that a following d, i, 0, u, x, or X conversion specifier 
applies to a short int or unsigned short int argument (the argument will have 
been promoted according to the integral promotions, and its value shall be 
converted to short int or unsigned short int before printing); or an optional | 
specifying that a following d, i, 0, u, x, or X conversion specifier applies to a 
long int or unsigned long int argument. If.an h or | appears with any other 
conversion specifier, it is ignored. 
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e A character that specifies the type of conversion to be applied. (Special AR 
extensions have been added.) The conversion specifiers and their meanings are: 


d, i, o, u, x, X 


The int argument is converted to signed decimal (d or i), unsigned octal 
(0), unsigned decimal (u), or unsigned hexadecimal notation (x or X); the 
letters abcdef are used for x conversion and the letters ABCDEF for X 
conversion. The precision specifies the minimum number of digits to 
appear; if the value being converted can be represented in fewer digits, it 
will be expanded with leading zeros. The default precision is 1. The 
result of converting a zero value with a precision of zero is no characters. 


¢ The int argument is converted to an unsigned char, and the resulting 
character is written. 


s The argument shail be a pointer to a null-terminated array of 8-bit chars. 
Characters from the string are printed up to (but not including) the 
terminating null character: if the precision is specified, no more than that 
many characters are printed. The string may be an array into which 
output was written via the sprintf routine. 


p The argument shall be a pointer to void. The value of the pointer is 
converted to a sequence of printable characters, in this format: 
0000:0000. ‘There are always exactly 4 digits to the right of the colon. 
The number of digits to the left of the colon is determined by the 
pointer’s value and the precision specified. Use this conversion to print 
80286 memory addresses. The segment number will appear to the left of 
the colon and the offset to the right. 


% A % is written. No argument is converted. 


\n Writes hexadecimal 0D 0A, the ASCII carriage-return and linefeed 
characters, No argument is converted. 


If a conversion specification is invalid, the behavior is undefined. 


If any argument is or points to an aggregate (except for an array of characters using 
%s conversion or any pointer using %p conversion), the behavior is undefined. 


In no case does a nonexistent or small field width cause truncation of a field; if the 
result of a conversion is wider than the field width, the field is expanded to contain 


the conversion result. 
Returns 


The printf routine returns the number of characters output. 


Example _ 
To print a date and time in the form “Sunday, July 3, 10:02,” where weekday and 
month are pointers to strings: 
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LAYER: 1 

{ 

unsigned char date_time [1/00]; 
unsigned char weekday {10}; 
unsigned char month [10]; 
unsigned short day; 

unsigned char hour; 

unsigned char min; 


} 
STATE: output_to_ printer 
CONDITIONS: KEYBOARD “ * 
ACTIONS: 
{ 
printf( “%s, %s %d, %.2d:%.2d\n", weekday, month, day, hour, min); 
} 
sprintf 
Synopsis 


extern int sprintf(string_ptr, format_ptr); 
unsigned char string {128}; 
const char * format_ptr; 


Description 


The sprintf routine is similar to the printf routine, except that sprintf writes output to 
a string, while printf writes output directly to the print buffer for printing. The sprintf 
routine is useful for writing formatted output to a display, printer, or file. 


The output is under control of the string pointed to by format_ptr that specifies how 
subsequent arguments are converted for output. If there are insufficient arguments 
for the format, the behavior is undefined. If the format is exhausted while arguments 
remain, the excess arguments are evaluated but otherwise ignored. The sprintf 
routine returns when the end of the format string is encountered. 


Inputs 


The first parameter is a pointer to the array to which output will be written. 


For the second parameter, see printf routine. 


Returns 


This routine returns the number of characters written into the array, not counting the 
added null terminating character. 


Example 


Refer again to the sample program for the displayf routine in Section 64.3(C), This 
time you also want to send the output-to a printer. By using the sprinéf routine, you 
only have to enter the format string once. 
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LAYER: 1 
{ 
unsigned char date_time [100]; 
unsigned char weekday {10}; 
unsigned char month [10]; 
unsigned Short day; 
unsigned char hour; 
unsigned char min; 


STATE: output_to_display_window_and_printer 
CONDITIONS: KEYBOARD * ” 
ACTIONS: 


{ 
sprint{(date_time, “%s, %s %d, %.2d: %,2d\n", weekday, month, day, hour, 


min); 
displayf(" %s", date_time); 
print{(“%s", date_time); 
) 


set_print_header 


Synopsis 


extern int set_print_header(format_ptr); 
const char * format_ptr; 


This routine writes output to the print buffer, to be printed after each form feed, 
under control of the string pointed to by format_pir. Paging is done automatically by 
the INTERVIEW. The set_print_header routine returns when the end of the format 


string is encountered. 


Inputs 

The format is composed of zero or more ordinary characters. Octal or hexadecimal 
values also may be input, with octal preceded by \ and hex by \x. Pad each value 
to three integers with leading zeroes. 


The status information shown above the prompt line on the display screens of the 
INTERVIEW can be sent to a printer with the following inputs: 


#d date (mm/dd/yy) 
#t time (hh:mm) 
#p page (not shown on the display screens) 
#b block number 
Ht # 
turn 


The set_print_header routine returns the length of the header (0-255), or a —1 if the 
header exceeds the buffer size. 
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Example 
If you want the date, time, and page number to appear in the heading on each page 


sent to a printer, enter the following: 


LAYER: 2 
STATE: header 
CONDITIONS: ENTER_STATE 
ACTIONS: 


{ 
set_print_header(“#H### fd #t Hp #HHANn”); 


} 
The printer output will look like this: 


## 09/01/89 09:30 Page ; 1 ## 


## 06/01/89 09:81 Page : 2 ## 


reset_print_page 


Synopsis 


extern int reset_print_page(); 


ription 


The reset_print_page routine resets the INTERVIEW'’s automatic page numbering for 
printer output to 1. 


Returns 


If the page number is successfully reset, the routine returns zero. If the print buffer 
is overrun, it returns -1. 


Example 


In the following example, a header with page numbering is assigned to printed output. 
(See set_print_header routine above.) Elsewhere in the program (not shown) the 
programmer has designated text to be printed. When the user presses the spacebar, 
a new header will appear on the next page output to the printer. That output will 
begin again with page 1. 
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LAYER: 1 
STATE: print_output 
CONDITIONS: ENTER_STATE 
ACTIONS: 


{ 
set_print_header("#d #t First Header #p\n”); 


} 
CONDITIONS: KEYBOARD “ " 


ACTIONS: 


{ 
Set_print_header(“t#d #t New Header #p\n”); 


reset_print_page(); 
} 


prints: 
Synopsis 


extern void prints (string ptr}; 
const char * string_ptr; 


Description 


The prints routine is similar to the displays routines, except that prints writes output 
to the print buffer for printing while displays writes output to the Display Window. 
The output is under contro! of the string pointed to by the argument. The prints 
routine returns when the end of the string is encountered. The softkey equivalent of 
this routine is the PRINT PROMPT action on the Protocol Spreadsheet. A PRINT 
PROMPT action automatically time-stamps the output. Although prints does not, you 
can create your own time or date stamp with set_print_header. 


Inputs 


The input is a pointer to a string composed of zero or more ordinary characters. 
The newline nonliteral sequence “\n” writes hex 0D OA (ASCII &'>) to the output 
string. Octal or hexadecimal values also may be included in the string, with octal 
preceded by \ and hex by \x. Pad each value to three integers with leading zeroes. 


Example 
The following entry 


LAYER: 1 
STATE: print_message 
CONDITIONS: KEYBOARD * ” 
ACTIONS: 


{ 
prints(“End of test."); 


produces the following output to a printer: 


End of test. 
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